VPP-346 More VPP doc fixes

- Fix issue in Doxy dependency check when nothing needs to be installed.
  'set -e' and plain '[]' logic don't mix well.
- Fix Makefile snafu when building Doxy output for a single file.
- Include only one of vnet/vnet/buffer.c/dpdk_buffer.c in docs depending on
  DPDKness. This could do with some improvement in future, eg to properly
  align the pre-doxy steps with what Doxy does.
- Fix rendering of 'inline' tag in Doxygen by having it interpret
  always_inline as "inline static".
- Bunch of duplicate CLI command structure names that confused docs and may
  one day have caused debugging issues.
- Several other Doxygen syntax issues fixed, like documenting non-existant
  parameters (usually just the wrong parameter name, typos, etc)

Change-Id: Ia8cca545e5de9f8750602bffa3c4548acc8971aa
Signed-off-by: Chris Luke <chrisy@flirble.org>

19 files changed, 99 insertions, 47 deletions

diff --git a/doxygen/Makefile b/doxygen/Makefile
index f3ddb2c991c..471b6fd7f15 100644
--- a/doxygen/Makefile
+++ b/doxygen/Makefile
@@ -40,8 +40,27 @@ DOXY_INPUT ?= \
 	vpp-api \
 	plugins
 
+# Files to exclude, from pre-Doxygen steps, eg because they're
+# selectively compiled.
+# Examples would be to exclude non-DPDK related sources when
+# there's a DPDK equivalent that conflicts.
+# This is specifically for the pre-Doxygen steps; Doxygen uses
+# @cond for this instead.
+DOXY_PRE_EXCLUDE ?= \
+	vlib/vlib/buffer.c
+
+# Generate a regexp for filenames to exclude
+DOXY_PRE_EXCLUDE_REGEXP = ($(subst .,\.,$(shell echo '$(strip $(DOXY_PRE_EXCLUDE))' | sed -e 's/ /|/g')))
+
+# Discover all the directories we might, possibly, maybe, have include files in
 DOXY_INCLUDE_PATH = $(shell set -e; cd $(WS_ROOT); for item in $(DOXY_INPUT); do find $$item -type d; done)
-DOXY_INCLUDE_PATH += $(shell set -e; cpp -v </dev/null 2>&1 | grep -A 1000 '\#include' | awk '/^ /{print $$1}')
+
+# Discover if we have CPP available
+CPP ?= $(shell which cpp)
+ifneq ($(strip $(CPP)),)
+# Add whatever directories CPP normally includes
+DOXY_INCLUDE_PATH += $(shell set -e; $(CPP) -v </dev/null 2>&1 | grep -A 1000 '\#include' | awk '/^ /{print $$1}')
+endif
 
 # Target directory for doxygen output
 DOXY_OUTPUT ?= $(BR)/docs
@@ -67,7 +86,7 @@ ifeq ($(OS_ID),ubuntu)
 		for i in $(DOC_DEB_DEPENDS); do \
 			dpkg-query --show $$i >/dev/null 2>&1 || inst="$$inst $$i"; \
 		done; \
-		[ "$$inst" ] && sudo apt-get $(CONFIRM) $(FORCE) install $$inst
+		if [ "$$inst" ]; then sudo apt-get $(CONFIRM) $(FORCE) install $$inst; fi
 else ifneq ("$(wildcard /etc/redhat-release)","")
 	@sudo yum install $(CONFIRM) $(DOC_RPM_DEPENDS)
 else
@@ -82,8 +101,10 @@ bootstrap-doxygen: $(BR)/.doxygen-bootstrap.ok
 $(BR)/.doxygen-siphon.dep: Makefile
 	set -e; rm -f "$@"; for input in $(DOXY_INPUT); do \
 		find "$(WS_ROOT)/$$input" -type f \
-			\( -name '*.[ch]' -or -name '*.dox' \) \
-			-print | sed -e "s/^/\$$(SIPHON_FILES): /" >> $@; \
+			\( -name '*.[ch]' -or -name '*.dox' \) -print \
+			| grep -v -E '^$(WS_ROOT)/$(DOXY_PRE_EXCLUDE_REGEXP)$$' \
+			| sed -e "s/^/\$$(SIPHON_FILES): /" \
+			>> $@; \
 	done
 
 # Include the source -> siphon dependencies
@@ -93,11 +114,13 @@ $(BR)/.doxygen-siphon.dep: Makefile
 $(SIPHON_FILES): $(DOXY_DIR)/siphon_generate.py $(BR)/.doxygen-bootstrap.ok
 	@rm -rf "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
 	@mkdir -p "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
-	set -e; for input in $(DOXY_INPUT); do \
+	@touch $(SIPHON_INPUT)/files
+	for input in $(DOXY_INPUT); do \
 		cd "$(WS_ROOT)"; \
 		find "$$input" -type f \
-			\( -name '*.[ch]' -or -name '*.dox' \) \
-			-print >> $(SIPHON_INPUT)/files; \
+			\( -name '*.[ch]' -or -name '*.dox' \) -print \
+			| grep -v -E '^$(DOXY_PRE_EXCLUDE_REGEXP)$$' \
+			>> $(SIPHON_INPUT)/files; \
 	done
 	set -e; cd "$(WS_ROOT)"; $(DOXY_DIR)/siphon_generate.py \
 		--output="$(SIPHON_INPUT)" \
diff --git a/doxygen/doxygen.cfg b/doxygen/doxygen.cfg
index 4eb0f373049..971a159502c 100644
--- a/doxygen/doxygen.cfg
+++ b/doxygen/doxygen.cfg
@@ -644,7 +644,7 @@ GENERATE_DEPRECATEDLIST= YES
 # sections, marked by \if <section_label> ... \endif and \cond <section_label>
 # ... \endcond blocks.
 
-ENABLED_SECTIONS       =
+ENABLED_SECTIONS       = DPDK
 
 # The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the
 # initial value of a variable or macro / define can have for it to appear in the
@@ -2061,7 +2061,8 @@ PREDEFINED             = \
 	__ORDER_LITTLE_ENDIAN__=1234 \
 	__BYTE_ORDER__=1234 \
 	__FLOAT_WORD_ORDER__=1234 \
-	DPDK=1
+	DPDK=1 \
+	always_inline:="static inline"
 	
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
diff --git a/doxygen/siphon_generate.py b/doxygen/siphon_generate.py
index 457757b510c..8b999114e52 100755
--- a/doxygen/siphon_generate.py
+++ b/doxygen/siphon_generate.py
@@ -80,6 +80,21 @@ def count_braces(str, count=0, found=False):
 # Collated output for each siphon
 output = {}
 
+# Build a list of known siphons
+known_siphons = []
+for item in siphon_patterns:
+	siphon = item[1]
+	if siphon not in known_siphons:
+		known_siphons.append(siphon)
+
+# Setup information for siphons we know about
+for siphon in known_siphons:
+	output[siphon] = {
+            "file": "%s/%s.siphon" % (args.output, siphon),
+            "global": {},
+            "items": [],
+        }
+
 # Pre-process file names in case they indicate a file with
 # a list of files
 files = []
@@ -233,12 +248,6 @@ for filename in files:
             if close_siphon is not None:
                 # Write the siphoned contents to the right place
                 siphon_name = close_siphon[0]
-                if siphon_name not in output:
-                    output[siphon_name] = {
-                        "global": {},
-                        "items": [],
-                        "file": "%s/%s.siphon" % (args.output, close_siphon[0])
-                    }
 
                 # Copy directives for the file
                 details = {}
diff --git a/vlib/vlib/buffer.c b/vlib/vlib/buffer.c
index 84cecc27a81..e1be2005424 100644
--- a/vlib/vlib/buffer.c
+++ b/vlib/vlib/buffer.c
@@ -37,6 +37,13 @@
  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/**
+ * @cond (!DPDK)
+ * @file
+ *
+ * Allocate/free network buffers.
+ */
+
 #include <vlib/vlib.h>
 
 uword
@@ -1527,6 +1534,7 @@ VLIB_CLI_COMMAND (show_buffers_command, static) = {
 };
 /* *INDENT-ON* */
 
+/** @endcond */
 /*
  * fd.io coding-style-patch-verification: ON
  *
diff --git a/vlib/vlib/buffer_funcs.h b/vlib/vlib/buffer_funcs.h
index 8b80be16053..497a6bb07a8 100644
--- a/vlib/vlib/buffer_funcs.h
+++ b/vlib/vlib/buffer_funcs.h
@@ -75,7 +75,7 @@ vlib_get_buffer (vlib_main_t * vm, u32 buffer_index)
 /** \brief Translate buffer pointer into buffer index
 
     @param vm - (vlib_main_t *) vlib main data structure pointer
-    @param b - (void *) buffer pointer
+    @param p - (void *) buffer pointer
     @return - (u32) buffer index
 */
 always_inline u32
@@ -135,7 +135,7 @@ vlib_buffer_index_length_in_chain (vlib_main_t * vm, u32 bi)
 /** \brief Copy buffer contents to memory
 
     @param vm - (vlib_main_t *) vlib main data structure pointer
-    @param bi - (u32) buffer index
+    @param buffer_index - (u32) buffer index
     @param contents - (u8 *) memory, <strong>must be large enough</strong>
     @return - (uword) length of buffer chain
 */
diff --git a/vlib/vlib/counter.h b/vlib/vlib/counter.h
index 28686b4bfd0..a79032065d9 100644
--- a/vlib/vlib/counter.h
+++ b/vlib/vlib/counter.h
@@ -168,7 +168,7 @@ typedef struct
 } vlib_counter_t;
 
 /** Add two combined counters, results in the first counter
-    @param [in/out] a - (vlib_counter_t *) dst counter
+    @param [in,out] a - (vlib_counter_t *) dst counter
     @param b - (vlib_counter_t *) src counter
 */
 
@@ -180,7 +180,7 @@ vlib_counter_add (vlib_counter_t * a, vlib_counter_t * b)
 }
 
 /** Subtract combined counters, results in the first counter
-    @param [in/out] a - (vlib_counter_t *) dst counter
+    @param [in,out] a - (vlib_counter_t *) dst counter
     @param b - (vlib_counter_t *) src counter
 */
 always_inline void
diff --git a/vlib/vlib/dpdk_buffer.c b/vlib/vlib/dpdk_buffer.c
index 828bc81f418..e617be2ab0a 100644
--- a/vlib/vlib/dpdk_buffer.c
+++ b/vlib/vlib/dpdk_buffer.c
@@ -37,6 +37,13 @@
  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/**
+ * @cond DPDK
+ * @file
+ *
+ * Allocate/free network buffers with DPDK.
+ */
+
 #include <rte_config.h>
 
 #include <rte_common.h>
@@ -1398,6 +1405,7 @@ buffer_state_validation_init (vlib_main_t * vm)
 VLIB_INIT_FUNCTION (buffer_state_validation_init);
 #endif
 
+/** @endcond */
 /*
  * fd.io coding-style-patch-verification: ON
  *
diff --git a/vlib/vlib/vlib_process_doc.h b/vlib/vlib/vlib_process_doc.h
index 43a51b57efa..a47c5e4bbe4 100644
--- a/vlib/vlib/vlib_process_doc.h
+++ b/vlib/vlib/vlib_process_doc.h
@@ -57,8 +57,8 @@
 
     Here's an example:
 
-    <pre>
-    #define EXAMPLE_POLL_PERIOD 10.0
+    <code><pre>
+    \#define EXAMPLE_POLL_PERIOD 10.0
 
     static uword
     example_process (vlib_main_t * vm, vlib_node_runtime_t * rt,
@@ -120,7 +120,7 @@
       .type = VLIB_NODE_TYPE_PROCESS,
       .name = "example-process",
     };
-    </pre>
+    </pre></code>
 
     In this example, the VLIB process node waits for an event to
     occur, or for 10 seconds to elapse. The code demuxes on the event
diff --git a/vnet/vnet/classify/policer_classify.c b/vnet/vnet/classify/policer_classify.c
index e4580a204bb..498f83b5e0d 100644
--- a/vnet/vnet/classify/policer_classify.c
+++ b/vnet/vnet/classify/policer_classify.c
@@ -161,7 +161,7 @@ set_policer_classify_command_fn (vlib_main_t * vm,
   return 0;
 }
 
-VLIB_CLI_COMMAND (set_input_acl_command, static) = {
+VLIB_CLI_COMMAND (set_policer_classify_command, static) = {
     .path = "set policer classify",
     .short_help =
     "set policer classify interface <int> [ip4-table <index>]\n"
diff --git a/vnet/vnet/devices/dpdk/node.c b/vnet/vnet/devices/dpdk/node.c
index 7b2914a800a..54a6a503cd0 100644
--- a/vnet/vnet/devices/dpdk/node.c
+++ b/vnet/vnet/devices/dpdk/node.c
@@ -660,9 +660,9 @@ poll_rate_limit (dpdk_main_t * dm)
     b->current_length </code> and dispatch directly to
     ip4-input-no-checksum, or ip6-input. Trace the packet if required.
 
-    @param vm vlib_main_t corresponding to the current thread
+    @param vm   vlib_main_t corresponding to the current thread
     @param node vlib_node_runtime_t
-    @param frame vlib_frame_t input-node, not used.
+    @param f    vlib_frame_t input-node, not used.
 
     @par Graph mechanics: buffer metadata, next index usage
 
diff --git a/vnet/vnet/ip/ip6_forward.c b/vnet/vnet/ip/ip6_forward.c
index b076ed0403e..c977960285d 100644
--- a/vnet/vnet/ip/ip6_forward.c
+++ b/vnet/vnet/ip/ip6_forward.c
@@ -3297,7 +3297,7 @@ add_del_ip6_interface_table (vlib_main_t * vm,
   return error;
 }
 
-VLIB_CLI_COMMAND (set_interface_ip_table_command, static) = {
+VLIB_CLI_COMMAND (set_interface_ip6_table_command, static) = {
   .path = "set interface ip6 table",
   .function = add_del_ip6_interface_table,
   .short_help = "set interface ip6 table <intfc> <table-id>"
@@ -3442,7 +3442,7 @@ show_ip6_local_command_fn (vlib_main_t * vm,
 
 
 
-VLIB_CLI_COMMAND (show_ip_local, static) = {
+VLIB_CLI_COMMAND (show_ip6_local, static) = {
   .path = "show ip6 local",
   .function = show_ip6_local_command_fn,
   .short_help = "Show ip6 local protocol table",
diff --git a/vnet/vnet/ip/ip_feature_registration.c b/vnet/vnet/ip/ip_feature_registration.c
index baf7ea27729..9505a09e20d 100644
--- a/vnet/vnet/ip/ip_feature_registration.c
+++ b/vnet/vnet/ip/ip_feature_registration.c
@@ -39,7 +39,7 @@
     feature subgraph arc, which needs to run before @c ip4-lookup.  In
     either base code or a plugin,
     <CODE><PRE>
-    #include <vnet/ip/ip_feature_registration.h>
+    \#include <vnet/ip/ip_feature_registration.h>
     </PRE></CODE>
 
     and add the new feature as shown:
@@ -57,7 +57,7 @@
     @c my-ip4-unicast-feature on an interface:
 
     <CODE><PRE>
-    ip4_main_t *im = &ip4_main;
+    ip4_main_t *im = \&ip4_main;
     ip_lookup_main_t *lm = &im->lookup_main;
     ip_config_main_t *rx_cm =
         &lm->feature_config_mains[VNET_IP_RX_UNICAST_FEAT];
diff --git a/vnet/vnet/ipsec-gre/node.c b/vnet/vnet/ipsec-gre/node.c
index 5a176088862..d20f248a6c8 100644
--- a/vnet/vnet/ipsec-gre/node.c
+++ b/vnet/vnet/ipsec-gre/node.c
@@ -62,9 +62,9 @@ u8 * format_ipsec_gre_rx_trace (u8 * s, va_list * args)
  *
  * This node remove GRE header.
  *
- * @param vm vlib_main_t corresponding to the current thread.
- * @param node vlib_node_runtime_t data for this node.
- * @param frame vlib_frame_t whose contents should be dispatched.
+ * @param vm         vlib_main_t corresponding to the current thread.
+ * @param node       vlib_node_runtime_t data for this node.
+ * @param from_frame vlib_frame_t whose contents should be dispatched.
  *
  * @par Graph mechanics: buffer metadata, next index usage
  *
diff --git a/vnet/vnet/unix/pcap.c b/vnet/vnet/unix/pcap.c
index 5c8a14bd29c..bba225f74ab 100644
--- a/vnet/vnet/unix/pcap.c
+++ b/vnet/vnet/unix/pcap.c
@@ -43,21 +43,24 @@
 /**
  * @file
  * @brief PCAP function.
- *  Usage
  *
- * #include <vnet/unix/pcap.h>
+ * Usage:
+ *
+ * <code><pre>
+ * \#include <vnet/unix/pcap.h>
  *
  * static pcap_main_t pcap = {
  *  .file_name = "/tmp/ip4",
  *  .n_packets_to_capture = 2,
  *  .packet_type = PCAP_PACKET_TYPE_ip,
  * };
+ * </pre></code>
  *
  * To add a buffer:
  *
- *  pcap_add_buffer (&pcap, vm, pi0, 128);
+ *  <code><pre>pcap_add_buffer (&pcap, vm, pi0, 128);</pre></code>
  *
- * File will be written after n_packets_to_capture or call to pcap_write (&pcap).
+ * File will be written after @c n_packets_to_capture or call to pcap_write (&amp;pcap).
  *
 */
 
diff --git a/vnet/vnet/unix/tapcli.c b/vnet/vnet/unix/tapcli.c
index 608b22098b1..c2328f0db89 100644
--- a/vnet/vnet/unix/tapcli.c
+++ b/vnet/vnet/unix/tapcli.c
@@ -802,10 +802,10 @@ static tapcli_interface_t *tapcli_get_new_tapif()
 /**
  * @brief Connect a TAP interface
  *
- * @param *vm - vlib_main_t
- * @param *intfc_name - u8
- * @param *hwaddr_arg - u8
- * @param *sw_if_index - u32
+ * @param vm - vlib_main_t
+ * @param intfc_name - u8
+ * @param hwaddr_arg - u8
+ * @param sw_if_indexp - u32
  *
  * @return rc - int
  *
diff --git a/vnet/vnet/vxlan-gpe/decap.c b/vnet/vnet/vxlan-gpe/decap.c
index 70cf08e116b..7eca3f6b8dc 100644
--- a/vnet/vnet/vxlan-gpe/decap.c
+++ b/vnet/vnet/vxlan-gpe/decap.c
@@ -96,7 +96,7 @@ static u8 * format_vxlan_gpe_with_length (u8 * s, va_list * args)
  * @param *vm
  * @param *node
  * @param *from_frame
- * @param ip_ip4
+ * @param is_ip4
  *
  * @return from_frame->n_vectors
  *
diff --git a/vppinfra/vppinfra/bihash_8_8.h b/vppinfra/vppinfra/bihash_8_8.h
index b5f4e3bfdfa..9b5da5a2b89 100644
--- a/vppinfra/vppinfra/bihash_8_8.h
+++ b/vppinfra/vppinfra/bihash_8_8.h
@@ -54,7 +54,7 @@ clib_bihash_hash_8_8 (clib_bihash_kv_8_8_t * v)
 
 /** Format a clib_bihash_kv_8_8_t instance
     @param s - u8 * vector under construction
-    @param v (vararg) - the (key,value) pair to format
+    @param args (vararg) - the (key,value) pair to format
     @return s - the u8 * vector under construction
 */
 static inline u8 *
diff --git a/vppinfra/vppinfra/bihash_doc.h b/vppinfra/vppinfra/bihash_doc.h
index da3d0a9b55b..e6ab9db6d30 100644
--- a/vppinfra/vppinfra/bihash_doc.h
+++ b/vppinfra/vppinfra/bihash_doc.h
@@ -108,7 +108,7 @@ void clib_bihash_free (clib_bihash * h);
 /** Add or delete a (key,value) pair from a bi-hash table
 
     @param h - the bi-hash table to search
-    @param add_kv - the (key,value) pair to add
+    @param add_v - the (key,value) pair to add
     @param is_add - add=1, delete=0
     @returns 0 on success, < 0 on error
     @note This function will replace an existing (key,value) pair if the
diff --git a/vppinfra/vppinfra/bitmap.h b/vppinfra/vppinfra/bitmap.h
index 4c27820d334..9e1ae493285 100644
--- a/vppinfra/vppinfra/bitmap.h
+++ b/vppinfra/vppinfra/bitmap.h
@@ -81,7 +81,7 @@ clib_bitmap_is_equal (uword * a, uword * b)
 }
 
 /** Duplicate a bitmap
-    @param ai - pointer to a bitmap
+    @param v - pointer to a bitmap
     @returns a duplicate of the bitmap
 */
 #define clib_bitmap_dup(v) vec_dup(v)
@@ -158,9 +158,9 @@ clib_bitmap_set_no_check (uword * a, uword i, uword new_value)
 
 /** Sets the ith bit of a bitmap to new_value
     Removes trailing zeros from the bitmap
-    @param a - pointer to the bitmap
+    @param ai - pointer to the bitmap
     @param i - the bit position to interrogate
-    @param new_value - new value for the bit
+    @param value - new value for the bit
     @returns the old value of the bit
 */
 always_inline uword *
@@ -588,7 +588,7 @@ _(andnoti, a = a & ~b, 1) _(ori, a = a | b, 0) _(xori, a = a ^ b, 1)
 /** Return a random bitmap of the requested length
     @param ai - pointer to the destination bitmap
     @param n_bits - number of bits to allocate
-    @param [in/out] seed - pointer to the random number seed
+    @param [in,out] seed - pointer to the random number seed
     @returns a reasonably random bitmap based. See random.h.
 */
      always_inline uword *