VPP-223 Various documentation fixes.

[Note: This is an amalgamation of two patches on master with
only the parts relevant to stable included. See 16bcf7d8 and
d4024f58]

This is a cleanup of some obvious syntactic issues with Doxygen
tags in the documentation. It is not an attempt to improve the
documentation itself.

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

35 files changed, 135 insertions, 97 deletions

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 c4c44849e1d..60c64573720 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 303b44e489a..27f6c13f3bb 100644
--- a/vnet/vnet/devices/dpdk/node.c
+++ b/vnet/vnet/devices/dpdk/node.c
@@ -674,9 +674,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/interface_cli.c b/vnet/vnet/interface_cli.c
index 7b9f5458eb5..654edcaa299 100644
--- a/vnet/vnet/interface_cli.c
+++ b/vnet/vnet/interface_cli.c
@@ -37,6 +37,11 @@
  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/**
+ * @file
+ * Interface CLI.
+ */
+
 #include <vnet/vnet.h>
 #include <vnet/ip/ip.h>
 #include <vppinfra/bitmap.h>
@@ -432,7 +437,9 @@ VLIB_CLI_COMMAND (clear_interface_counters_command, static) = {
 };
 /* *INDENT-ON* */
 
-/** \detail
+/**
+ * Parse subinterface names.
+ *
  * The following subinterface syntax is supported. The first two are for
  * backwards compatability:
  *
diff --git a/vnet/vnet/ip/ip6_forward.c b/vnet/vnet/ip/ip6_forward.c
index 1e4afa8d0c0..e572b4dd53c 100644
--- a/vnet/vnet/ip/ip6_forward.c
+++ b/vnet/vnet/ip/ip6_forward.c
@@ -3075,7 +3075,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>"
@@ -3220,7 +3220,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/lookup.h b/vnet/vnet/ip/lookup.h
index 2b682d27195..eb9662720ce 100644
--- a/vnet/vnet/ip/lookup.h
+++ b/vnet/vnet/ip/lookup.h
@@ -37,11 +37,15 @@
  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-/** @file Definitions for all things IP (v4|v6) unicast and multicast lookup related.
-    - Adjacency definitions and registration
-    - callbacks on route add
-    - callbacks on interface address change
+/**
+ * @file
+ * Definitions for all things IP (v4|v6) unicast and multicast lookup related.
+ *
+ * - Adjacency definitions and registration.
+ * - Callbacks on route add.
+ * - Callbacks on interface address change.
  */
+
 #ifndef included_ip_lookup_h
 #define included_ip_lookup_h
 
diff --git a/vnet/vnet/ipsec-gre/error.def b/vnet/vnet/ipsec-gre/error.def
index 0d7b4686f8a..d84e8ed1759 100644
--- a/vnet/vnet/ipsec-gre/error.def
+++ b/vnet/vnet/ipsec-gre/error.def
@@ -13,7 +13,7 @@
  * limitations under the License.
  */
 /**
- * @file error.def
+ * @file
  * @brief L2-GRE over IPSec errors.
  */
 
diff --git a/vnet/vnet/ipsec-gre/interface.c b/vnet/vnet/ipsec-gre/interface.c
index 3e5d3954341..dbf9df5628a 100644
--- a/vnet/vnet/ipsec-gre/interface.c
+++ b/vnet/vnet/ipsec-gre/interface.c
@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 /**
- * @file interface.c
+ * @file
  * @brief L2-GRE over IPSec tunnel interface.
  *
  * Creates ipsec-gre tunnel interface.
diff --git a/vnet/vnet/ipsec-gre/ipsec_gre.c b/vnet/vnet/ipsec-gre/ipsec_gre.c
index 24ec6f4e9d6..3d1b54fc7f9 100644
--- a/vnet/vnet/ipsec-gre/ipsec_gre.c
+++ b/vnet/vnet/ipsec-gre/ipsec_gre.c
@@ -13,7 +13,7 @@
  * limitations under the License.
  */
 /**
- * @file ipsec_gre.c
+ * @file
  * @brief L2-GRE over IPSec packet processing.
  *
  * Add GRE header to thr packet and send it to the esp-encrypt node.
diff --git a/vnet/vnet/ipsec-gre/ipsec_gre.h b/vnet/vnet/ipsec-gre/ipsec_gre.h
index 2b66c6a6e8a..a2ca64b6f74 100644
--- a/vnet/vnet/ipsec-gre/ipsec_gre.h
+++ b/vnet/vnet/ipsec-gre/ipsec_gre.h
@@ -13,7 +13,7 @@
  * limitations under the License.
  */
 /**
- * @file ipsec_gre.h
+ * @file
  * @brief L2-GRE over IPSec packet processing.
 */
 
diff --git a/vnet/vnet/ipsec-gre/node.c b/vnet/vnet/ipsec-gre/node.c
index 131025521f3..d20f248a6c8 100644
--- a/vnet/vnet/ipsec-gre/node.c
+++ b/vnet/vnet/ipsec-gre/node.c
@@ -13,10 +13,10 @@
  * limitations under the License.
  */
 /**
- * @file node.c
+ * @file
  * @brief L2-GRE over IPSec packet processing.
  *
- * Removes GRE header from the packet and send it to the l2-input node.
+ * Removes GRE header from the packet and sends it to the l2-input node.
 */
 
 #include <vlib/vlib.h>
@@ -62,13 +62,13 @@ 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
  *
- * <em>Uses:<em>
+ * <em>Uses:</em>
  * - <code>ip->src_address</code> and <code>ip->dst_address</code>
  *     - Match tunnel by source and destination addresses in GRE IP header.
  *
diff --git a/vnet/vnet/l2/l2_bd.c b/vnet/vnet/l2/l2_bd.c
index a872453a98b..7615583a581 100644
--- a/vnet/vnet/l2/l2_bd.c
+++ b/vnet/vnet/l2/l2_bd.c
@@ -35,7 +35,7 @@
 bd_main_t bd_main;
 
 /**
-  Init bridge domain if not done already
+  Init bridge domain if not done already.
   For feature bitmap, set all bits except ARP termination
 */
 void
@@ -173,7 +173,7 @@ VLIB_INIT_FUNCTION (l2bd_init);
 
 
 /**
-    Set the learn/forward/flood flags for the bridge domain
+    Set the learn/forward/flood flags for the bridge domain.
     Return 0 if ok, non-zero if for an error.
 */
 u32
@@ -222,7 +222,7 @@ bd_set_flags (vlib_main_t * vm, u32 bd_index, u32 flags, u32 enable)
 }
 
 /**
-   set bridge-domain learn enable/disable
+   Set bridge-domain learn enable/disable.
    The CLI format is:
    set bridge-domain learn <bd_id> [disable]
 */
@@ -277,7 +277,7 @@ VLIB_CLI_COMMAND (bd_learn_cli, static) = {
 /* *INDENT-ON* */
 
 /**
-    set bridge-domain forward enable/disable
+    Set bridge-domain forward enable/disable.
     The CLI format is:
     set bridge-domain forward <bd_index> [disable]
 */
@@ -331,7 +331,7 @@ VLIB_CLI_COMMAND (bd_fwd_cli, static) = {
 /* *INDENT-ON* */
 
 /**
-    set bridge-domain flood enable/disable
+    Set bridge-domain flood enable/disable.
     The CLI format is:
     set bridge-domain flood <bd_index> [disable]
 */
@@ -386,7 +386,7 @@ VLIB_CLI_COMMAND (bd_flood_cli, static) = {
 /* *INDENT-ON* */
 
 /**
-    set bridge-domain unkown-unicast flood enable/disable
+    Set bridge-domain unkown-unicast flood enable/disable.
     The CLI format is:
     set bridge-domain uu-flood <bd_index> [disable]
 */
@@ -441,7 +441,7 @@ VLIB_CLI_COMMAND (bd_uu_flood_cli, static) = {
 /* *INDENT-ON* */
 
 /**
-    set bridge-domain arp term enable/disable
+    Set bridge-domain arp term enable/disable.
     The CLI format is:
     set bridge-domain arp term <bridge-domain-id> [disable]
 */
@@ -494,11 +494,15 @@ VLIB_CLI_COMMAND (bd_arp_term_cli, static) = {
 
 
 /**
+ * Add/delete IP address to MAC address mapping.
+ *
  * The clib hash implementation stores uword entries in the hash table.
  * The hash table mac_by_ip4 is keyed via IP4 address and store the
  * 6-byte MAC address directly in the hash table entry uword.
- * This only works for 64-bit processor with 8-byte uword; which means
- * this code *WILL NOT WORK* for a 32-bit prcessor with 4-byte uword.
+ *
+ * @warning This only works for 64-bit processor with 8-byte uword;
+ * which means this code *WILL NOT WORK* for a 32-bit prcessor with
+ * 4-byte uword.
  */
 u32
 bd_add_del_ip_mac (u32 bd_index,
@@ -547,7 +551,7 @@ bd_add_del_ip_mac (u32 bd_index,
 }
 
 /**
-    set bridge-domain arp entry add/delete
+    Set bridge-domain arp entry add/delete.
     The CLI format is:
     set bridge-domain arp entry <bd-id> <ip-addr> <mac-addr> [del]
 */
@@ -662,7 +666,7 @@ format_vtr (u8 * s, va_list * args)
 }
 
 /**
-   show bridge-domain state
+   Show bridge-domain state.
    The CLI format is:
    show bridge-domain [<bd_index>]
 */
diff --git a/vnet/vnet/l2/l2_efp_filter.c b/vnet/vnet/l2/l2_efp_filter.c
index 221db9abc73..2038dce2737 100644
--- a/vnet/vnet/l2/l2_efp_filter.c
+++ b/vnet/vnet/l2/l2_efp_filter.c
@@ -97,7 +97,7 @@ typedef enum
 
 /**
  *  Extract fields from the packet that will be used in interface
- *  classification
+ *  classification.
  */
 static_always_inline void
 extract_keys (vnet_main_t * vnet_main,
@@ -524,7 +524,7 @@ VLIB_NODE_FUNCTION_MULTIARCH (l2_efp_filter_node, l2_efp_filter_node_fn)
 VLIB_INIT_FUNCTION (l2_efp_filter_init);
 
 
-/** Enable/disable the EFP Filter check on the subinterface */
+/** Enable/disable the EFP Filter check on the subinterface. */
 void
 l2_efp_filter_configure (vnet_main_t * vnet_main, u32 sw_if_index, u32 enable)
 {
@@ -534,7 +534,7 @@ l2_efp_filter_configure (vnet_main_t * vnet_main, u32 sw_if_index, u32 enable)
 
 
 /**
- * set subinterface egress efp filter enable/disable
+ * Set subinterface egress efp filter enable/disable.
  * The CLI format is:
  *    set interface l2 efp-filter <interface> [disable]]
  */
diff --git a/vnet/vnet/l2/l2_fib.c b/vnet/vnet/l2/l2_fib.c
index 4275e884ce0..97620bfba6b 100644
--- a/vnet/vnet/l2/l2_fib.c
+++ b/vnet/vnet/l2/l2_fib.c
@@ -97,7 +97,7 @@ l2fib_table_dump (u32 bd_index, l2fib_entry_key_t ** l2fe_key,
     }
 }
 
-/** Display the contents of the l2fib */
+/** Display the contents of the l2fib. */
 static clib_error_t *
 show_l2fib (vlib_main_t * vm,
 	    unformat_input_t * input, vlib_cli_command_t * cmd)
@@ -228,8 +228,8 @@ l2fib_clear_table (uint keep_static)
   l2learn_main.global_learn_count = 0;
 }
 
-/** Clear all entries in L2FIB
- * TODO: Later we may want a way to remove only the non-static entries
+/** Clear all entries in L2FIB.
+ * @TODO: Later we may want a way to remove only the non-static entries
  */
 static clib_error_t *
 clear_l2fib (vlib_main_t * vm,
@@ -286,7 +286,7 @@ l2fib_add_entry (u64 mac,
 }
 
 /**
- * Add an entry to the L2FIB
+ * Add an entry to the L2FIB.
  * The CLI format is:
  *    l2fib add <mac> <bd> <intf> [static] [bvi]
  *    l2fib add <mac> <bd> filter
@@ -517,7 +517,7 @@ l2fib_del_entry (u64 mac, u32 bd_index)
 }
 
 /**
- * Delete an entry from the L2FIB
+ * Delete an entry from the L2FIB.
  * The CLI format is:
  *    l2fib del <mac> <bd-id>
  */
diff --git a/vnet/vnet/l2/l2_flood.c b/vnet/vnet/l2/l2_flood.c
index 0654fe293b8..05df2a014d9 100644
--- a/vnet/vnet/l2/l2_flood.c
+++ b/vnet/vnet/l2/l2_flood.c
@@ -490,7 +490,7 @@ VLIB_INIT_FUNCTION (l2flood_init);
 
 
 
-/** Add the L3 input node for this ethertype to the next nodes structure */
+/** Add the L3 input node for this ethertype to the next nodes structure. */
 void
 l2flood_register_input_type (vlib_main_t * vm,
 			     ethernet_type_t type, u32 node_index)
@@ -505,7 +505,7 @@ l2flood_register_input_type (vlib_main_t * vm,
 
 
 /**
- * set subinterface flood enable/disable
+ * Set subinterface flood enable/disable.
  * The CLI format is:
  * set interface l2 flood <interface> [disable]
  */
diff --git a/vnet/vnet/l2/l2_fwd.c b/vnet/vnet/l2/l2_fwd.c
index 4950b23a8f0..8fa355e01a0 100644
--- a/vnet/vnet/l2/l2_fwd.c
+++ b/vnet/vnet/l2/l2_fwd.c
@@ -104,7 +104,7 @@ typedef enum
   L2FWD_N_NEXT,
 } l2fwd_next_t;
 
-/** Forward one packet based on the mac table lookup result */
+/** Forward one packet based on the mac table lookup result. */
 
 static_always_inline void
 l2fwd_process (vlib_main_t * vm,
@@ -400,7 +400,7 @@ VLIB_NODE_FUNCTION_MULTIARCH (l2fwd_node, l2fwd_node_fn)
 VLIB_INIT_FUNCTION (l2fwd_init);
 
 
-/** Add the L3 input node for this ethertype to the next nodes structure */
+/** Add the L3 input node for this ethertype to the next nodes structure. */
 void
 l2fwd_register_input_type (vlib_main_t * vm,
 			   ethernet_type_t type, u32 node_index)
@@ -415,7 +415,7 @@ l2fwd_register_input_type (vlib_main_t * vm,
 
 
 /**
- * set subinterface forward enable/disable
+ * Set subinterface forward enable/disable.
  * The CLI format is:
  *   set interface l2 forward <interface> [disable]
  */
diff --git a/vnet/vnet/l2/l2_input.c b/vnet/vnet/l2/l2_input.c
index 9607031fcda..ef1e00ce66b 100644
--- a/vnet/vnet/l2/l2_input.c
+++ b/vnet/vnet/l2/l2_input.c
@@ -486,7 +486,7 @@ VLIB_NODE_FUNCTION_MULTIARCH (l2input_node, l2input_node_fn)
 VLIB_INIT_FUNCTION (l2input_init);
 
 
-/** Get a pointer to the config for the given interface */
+/** Get a pointer to the config for the given interface. */
 l2_input_config_t *
 l2input_intf_config (u32 sw_if_index)
 {
@@ -496,7 +496,7 @@ l2input_intf_config (u32 sw_if_index)
   return vec_elt_at_index (mp->configs, sw_if_index);
 }
 
-/** Enable (or disable) the feature in the bitmap for the given interface */
+/** Enable (or disable) the feature in the bitmap for the given interface. */
 u32
 l2input_intf_bitmap_enable (u32 sw_if_index, u32 feature_bitmap, u32 enable)
 {
@@ -532,10 +532,10 @@ l2input_set_bridge_features (u32 bd_index, u32 feat_mask, u32 feat_value)
 
 /**
  * Set the subinterface to run in l2 or l3 mode.
- * for L3 mode, just the sw_if_index is specified
- * for bridged mode, the bd id and bvi flag are also specified
- * for xconnect mode, the peer sw_if_index is also specified
- * Return 0 if ok, or non-0 if there was an error
+ * For L3 mode, just the sw_if_index is specified.
+ * For bridged mode, the bd id and bvi flag are also specified.
+ * For xconnect mode, the peer sw_if_index is also specified.
+ * Return 0 if ok, or non-0 if there was an error.
  */
 
 u32
@@ -766,7 +766,7 @@ set_int_l2_mode (vlib_main_t * vm, vnet_main_t * vnet_main, u32 mode, u32 sw_if_
 }
 
 /**
- * set subinterface in bridging mode with a bridge-domain ID
+ * Set subinterface in bridging mode with a bridge-domain ID.
  * The CLI format is:
  *   set interface l2 bridge <interface> <bd> [bvi] [split-horizon-group]
  */
@@ -842,7 +842,7 @@ VLIB_CLI_COMMAND (int_l2_bridge_cli, static) = {
 /* *INDENT-ON* */
 
 /**
- * set subinterface in xconnect mode with another interface
+ * Set subinterface in xconnect mode with another interface.
  * The CLI format is:
  *   set interface l2 xconnect <interface> <peer interface>
  */
@@ -892,7 +892,7 @@ VLIB_CLI_COMMAND (int_l2_xc_cli, static) = {
 /* *INDENT-ON* */
 
 /**
- * set subinterface in L3 mode
+ * Set subinterface in L3 mode.
  * The CLI format is:
  *   set interface l3 <interface>
  */
@@ -931,6 +931,7 @@ VLIB_CLI_COMMAND (int_l3_cli, static) = {
 /* *INDENT-ON* */
 
 /**
+ * Show interface mode.
  * The CLI format is:
  *    show mode [<if-name1> <if-name2> ...]
  */
diff --git a/vnet/vnet/l2/l2_learn.c b/vnet/vnet/l2/l2_learn.c
index 30f5617f05e..96d4816e1e6 100644
--- a/vnet/vnet/l2/l2_learn.c
+++ b/vnet/vnet/l2/l2_learn.c
@@ -29,8 +29,9 @@
 #include <vppinfra/error.h>
 #include <vppinfra/hash.h>
 
-/*
- * Ethernet bridge learning
+/**
+ * @file
+ * Ethernet bridge learning.
  *
  * Populate the mac table with entries mapping the packet's source mac + bridge
  * domain ID to the input sw_if_index.
@@ -102,7 +103,7 @@ typedef enum
 } l2learn_next_t;
 
 
-/** Perform learning on one packet based on the mac table lookup result */
+/** Perform learning on one packet based on the mac table lookup result. */
 
 static_always_inline void
 l2learn_process (vlib_node_runtime_t * node,
@@ -462,7 +463,7 @@ VLIB_INIT_FUNCTION (l2learn_init);
 
 
 /**
- * set subinterface learn enable/disable
+ * Set subinterface learn enable/disable.
  * The CLI format is:
  *    set interface l2 learn <interface> [disable]
  */
diff --git a/vnet/vnet/l2/l2_output.c b/vnet/vnet/l2/l2_output.c
index 8bc43744d9f..85678caf6b7 100644
--- a/vnet/vnet/l2/l2_output.c
+++ b/vnet/vnet/l2/l2_output.c
@@ -73,9 +73,10 @@ static char *l2output_error_strings[] = {
 };
 
 /**
- * Return 0 if split horizon check passes, otherwise return non-zero
+ * Check for split horizon violations.
+ * Return 0 if split horizon check passes, otherwise return non-zero.
  * Packets should not be transmitted out an interface with the same
- * split-horizon group as the input interface, except if the shg is 0
+ * split-horizon group as the input interface, except if the @c shg is 0
  * in which case the check always passes.
  */
 static_always_inline u32
@@ -592,7 +593,7 @@ output_node_mapping_send_rpc (u32 node_index, u32 sw_if_index)
 #endif
 
 
-/** Create a mapping in the next node mapping table for the given sw_if_index */
+/** Create a mapping in the next node mapping table for the given sw_if_index. */
 u32
 l2output_create_output_node_mapping (vlib_main_t * vlib_main, vnet_main_t * vnet_main, u32 node_index,	/* index of current node */
 				     u32 * output_node_index_vec,
@@ -660,7 +661,7 @@ l2output_intf_config (u32 sw_if_index)
   return vec_elt_at_index (mp->configs, sw_if_index);
 }
 
-/** Enable (or disable) the feature in the bitmap for the given interface */
+/** Enable (or disable) the feature in the bitmap for the given interface. */
 void
 l2output_intf_bitmap_enable (u32 sw_if_index, u32 feature_bitmap, u32 enable)
 {
diff --git a/vnet/vnet/l2/l2_output_acl.c b/vnet/vnet/l2/l2_output_acl.c
index 4597d42e945..94a4d66b48f 100644
--- a/vnet/vnet/l2/l2_output_acl.c
+++ b/vnet/vnet/l2/l2_output_acl.c
@@ -306,8 +306,8 @@ VLIB_NODE_FUNCTION_MULTIARCH (l2_outacl_node, l2_outacl_node_fn)
 VLIB_INIT_FUNCTION (l2_outacl_init);
 
 #if 0
-/** @todo maybe someone will add output ACL's in the future
- * set subinterface outacl enable/disable
+/** @todo maybe someone will add output ACL's in the future.
+ * Set subinterface outacl enable/disable.
  * The CLI format is:
  *    set interface acl output <interface> [disable]
  */
diff --git a/vnet/vnet/l2/l2_vtr.c b/vnet/vnet/l2/l2_vtr.c
index 6250074e303..3ec8b8a7d36 100644
--- a/vnet/vnet/l2/l2_vtr.c
+++ b/vnet/vnet/l2/l2_vtr.c
@@ -30,7 +30,7 @@
 #include <vlib/cli.h>
 
 
-/** Just a placeholder. Also ensures file is not eliminated by linker. */
+/** Just a placeholder; ensures file is not eliminated by linker. */
 clib_error_t *
 l2_vtr_init (vlib_main_t * vm)
 {
@@ -254,7 +254,7 @@ done:
 }
 
 /**
- *  Get vtag tag rewrite on the given interface.
+ * Get vtag tag rewrite on the given interface.
  * Return 1 if there is an error, 0 if ok
  */
 u32
@@ -411,7 +411,7 @@ done:
 }
 
 /**
- * set subinterface vtr enable/disable
+ * Set subinterface vtr enable/disable.
  * The CLI format is:
  *    set interface l2 tag-rewrite <interface> [disable | pop 1 | pop 2 | push {dot1q|dot1ad} <tag> [<tag>]]
  *
diff --git a/vnet/vnet/l2/l2_xcrw.c b/vnet/vnet/l2/l2_xcrw.c
index 95219e6e9f0..344a8b96506 100644
--- a/vnet/vnet/l2/l2_xcrw.c
+++ b/vnet/vnet/l2/l2_xcrw.c
@@ -14,7 +14,8 @@
  */
 #include <vnet/l2/l2_xcrw.h>
 
-/*
+/**
+ * @file
  * General L2 / L3 cross-connect, used to set up
  * "L2 interface <--> your-favorite-tunnel-encap" tunnels.
  *
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/unix/tuntap.c b/vnet/vnet/unix/tuntap.c
index 83e7ec4f590..b3fbc7f32e7 100644
--- a/vnet/vnet/unix/tuntap.c
+++ b/vnet/vnet/unix/tuntap.c
@@ -786,9 +786,9 @@ tuntap_ip4_add_del_interface_address (ip4_main_t * im,
 }
 
 /**
- * @brief workaround for a known #include bug
- * #include <linux/ipv6.h> causes multiple definitions if
- * netinet/in.h is also included.
+ * @brief workaround for a known include file bug.
+ * including @c <linux/ipv6.h> causes multiple definitions if
+ * @c <netinet/in.h is also included.
  */
 struct in6_ifreq {
 	struct in6_addr	ifr6_addr;
@@ -797,7 +797,7 @@ struct in6_ifreq {
 };
 
 /**
- * @brief Add or Del tun/tap interface address
+ * @brief Add or Del tun/tap interface address.
  *
  * Both the v6 interface address API and the way ifconfig
  * displays subinterfaces differ from their v4 couterparts.
diff --git a/vnet/vnet/vxlan-gpe/decap.c b/vnet/vnet/vxlan-gpe/decap.c
index 315a0a131ad..4fc7f35f104 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/bihash_template.c b/vppinfra/vppinfra/bihash_template.c
index a8d095c9758..2ad8293094c 100644
--- a/vppinfra/vppinfra/bihash_template.c
+++ b/vppinfra/vppinfra/bihash_template.c
@@ -13,7 +13,7 @@
  * limitations under the License.
  */
 
-/** @if DOCUMENTATION_IS_IN_BIHASH_DOC_H */
+/** @cond DOCUMENTATION_IS_IN_BIHASH_DOC_H */
 
 void BV (clib_bihash_init)
   (BVT (clib_bihash) * h, char *name, u32 nbuckets, uword memory_size)
@@ -444,7 +444,7 @@ void BV (clib_bihash_foreach_key_value_pair)
     }
 }
 
-/** @endif */
+/** @endcond */
 
 /*
  * fd.io coding-style-patch-verification: ON
diff --git a/vppinfra/vppinfra/bihash_template.h b/vppinfra/vppinfra/bihash_template.h
index 07c3e7daec7..a8bb27ffb0e 100644
--- a/vppinfra/vppinfra/bihash_template.h
+++ b/vppinfra/vppinfra/bihash_template.h
@@ -14,7 +14,7 @@
  * limitations under the License.
 */
 
-/** @if DOCUMENTATION_IS_IN_BIHASH_DOC_H */
+/** @cond DOCUMENTATION_IS_IN_BIHASH_DOC_H */
 
 /*
  * Note: to instantiate the template multiple times in a single file,
@@ -203,7 +203,7 @@ static inline int BV (clib_bihash_search_inline_2)
 
 #endif /* __included_bihash_template_h__ */
 
-/** @endif */
+/** @endcond */
 
 /*
  * fd.io coding-style-patch-verification: ON
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 *