VPP-346 A swathe of doc fixes

Fixes various Doxygen warnings and other structural defects.

Note: This does not attempt to improve the content of the
documentation; only to improve the syntax and structure of it
and in some cases the consistency.

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

27 files changed, 208 insertions, 112 deletions

diff --git a/doxygen/Makefile b/doxygen/Makefile
index 8e916526..df7d07d7 100644
--- a/doxygen/Makefile
+++ b/doxygen/Makefile
@@ -40,6 +40,9 @@ DOXY_INPUT ?= \
 	vpp-api \
 	plugins
 
+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}')
+
 # Target directory for doxygen output
 DOXY_OUTPUT ?= $(BR)/docs
 
@@ -114,6 +117,7 @@ doxygen: $(SIPHON_DOCS)
 	    ROOT="$(WS_ROOT)" \
 	    BUILD_ROOT="$(BR)" \
 	    INPUT="$(addprefix $(WS_ROOT)/,$(DOXY_INPUT)) $(EXTRA_DOXY_INPUT)" \
+	    INCLUDE_PATH="$(DOXY_INCLUDE_PATH)" \
 	    HTML=YES \
 	    VERSION="`git describe --tags --dirty`" \
 	    doxygen $(DOXY_DIR)/doxygen.cfg
diff --git a/doxygen/doxygen.cfg b/doxygen/doxygen.cfg
index 82687cac..4eb0f373 100644
--- a/doxygen/doxygen.cfg
+++ b/doxygen/doxygen.cfg
@@ -234,6 +234,7 @@ ALIASES                =
 ALIASES += "node=@xrefitem nodes \"Node Identifier\" \"Node Identifiers\" @c "
 
 ## Formatting for CLI commands and output
+ALIASES += "cli{1}=<code><pre>\1</code></pre>"
 ALIASES += "clistart=<code><pre>"
 ALIASES += "cliend=</pre></code>"
 
@@ -914,6 +915,7 @@ INPUT_FILTER           =
 
 FILTER_PATTERNS        = \
 	*.c=$(ROOT)/doxygen/filter_c.py \
+	*.h=$(ROOT)/doxygen/filter_h.py \
 	*.api=$(ROOT)/doxygen/filter_api.py
 
 # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
@@ -2035,7 +2037,7 @@ SEARCH_INCLUDES        = YES
 # preprocessor.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
-INCLUDE_PATH           = $(INPUT)
+INCLUDE_PATH           = $(INCLUDE_PATH)
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the
diff --git a/doxygen/filter_c.py b/doxygen/filter_c.py
index 733fdefb..30b933ba 100755
--- a/doxygen/filter_c.py
+++ b/doxygen/filter_c.py
@@ -22,26 +22,45 @@ if len(sys.argv) < 2:
     sys.exit(1)
 
 replace_patterns = [
-    # Search for VLIB_CLI_COMMAND, extract its parameter and add a docblock for it
-    ( re.compile("(?P<m>VLIB_CLI_COMMAND)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (\g<name>) */ vlib_cli_command_t \g<name>"),
-
-    # Search for VLIB_REGISTER_NODE, extract its parameter and add a docblock for it
-    ( re.compile("(?P<m>VLIB_REGISTER_NODE)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (\g<name>) */ vlib_node_registration_t \g<name>"),
+    # Search for VLIB_CLI_COMMAND, extract its parameters and add a docblock for it
+    ( re.compile("(?P<m>VLIB_CLI_COMMAND)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"),
+        r"/** @brief (@em constructor) \g<m> (\g<name>) */ vlib_cli_command_t \g<name>"),
+    ( re.compile("(?P<m>VLIB_CLI_COMMAND)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<qual>[^)]*)[)]"),
+        r"/** @brief (@em constructor) \g<m> (\g<name>) */ \g<qual> vlib_cli_command_t \g<name>"),
+
+    # Search for VLIB_REGISTER_NODE, extract its parameters and add a docblock for it
+    ( re.compile("(?P<m>VLIB_REGISTER_NODE)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"),
+        r"/** @brief (@em constructor) \g<m> (\g<name>) */ vlib_node_registration_t \g<name>"),
+    ( re.compile("(?P<m>VLIB_REGISTER_NODE)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<qual>[^)]*)[)]"),
+        r"/** @brief (@em constructor) \g<m> (\g<name>) */ \g<qual> vlib_node_registration_t \g<name>"),
 
     # Search for VLIB_INIT_FUNCTION, extract its parameter and add a docblock for it
-    ( re.compile("(?P<m>VLIB_INIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"), r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ vlib_init_function_t * _vlib_init_function_\g<name>"),
-    ( re.compile("(?P<m>VLIB_DECLARE_INIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"), r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ vlib_init_function_t * _vlib_init_function_\g<name>"),
+    ( re.compile("(?P<m>VLIB_INIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"),
+        r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ vlib_init_function_t * _vlib_init_function_\g<name>"),
+    ( re.compile("(?P<m>VLIB_DECLARE_INIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)[)]"),
+        r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ vlib_init_function_t * _vlib_init_function_\g<name>"),
+
+    # Search for VLIB_LOOP_ENTER_FUNCTION, extract the parameters and add a docblock for it
+    ( re.compile("(?P<m>VLIB_MAIN_LOOP_ENTER_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"),
+        r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ _vlib_main_loop_enter_\g<name>"),
+    ( re.compile("(?P<m>VLIB_MAIN_LOOP_EXIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"),
+        r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ _vlib_main_loop_exit_\g<name>"),
+
+    # Search for VLIB_CONFIG_FUNCTION, extract the parameters and add a docblock for it
+    ( re.compile("(?P<m>VLIB_CONFIG_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<n>\"[^\"]+\")(,[^)]*)?[)]"),
+        r"/** @brief (@em constructor) \g<m> (\g<name>, \g<n>) */ vlib_config_function_runtime_t _vlib_config_function_\g<name>"),
+    ( re.compile("(?P<m>VLIB_EARLY_CONFIG_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<n>\"[^\"]+\")(,[^)]*)?[)]"),
+        r"/** @brief (@em constructor) \g<m> (\g<name>, \g<n>) */ vlib_config_function_runtime_t _vlib_config_function_\g<name>"),
 
-    # Search for VLIB_LOOP_ENTER_FUNCTION, extract the 1st parameter (ignore any others) and add a docblock for it
-    ( re.compile("(?P<m>VLIB_MAIN_LOOP_ENTER_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ _vlib_main_loop_enter_\g<name>"),
-    ( re.compile("(?P<m>VLIB_MAIN_LOOP_EXIT_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+)(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (@ref \g<name>) */ _vlib_main_loop_exit_\g<name>"),
+    # Search for "format_thing" and "unformat_thing" when used as a function pointer and add parens
+    ( re.compile("(?P<pre>(^|,)\s*)(?P<name>(un)?format_[a-zA-Z0-9_]+)(?P<post>\s*(,|$))"),
+        r"\g<pre>\g<name>()\g<post>" ),
 
-    # Search for VLIB_CONFIG_FUNCTION, extract the 1st parameter (ignore any others) and add a docblock for it
-    ( re.compile("(?P<m>VLIB_CONFIG_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<n>\"[^\"]+\")(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (\g<name>, \g<n>) */ vlib_config_function_runtime_t _vlib_config_function_\g<name>"),
-    ( re.compile("(?P<m>VLIB_EARLY_CONFIG_FUNCTION)\s*[(](?P<name>[a-zA-Z0-9_]+),\s*(?P<n>\"[^\"]+\")(,[^)]*)?[)]"), r"/** @brief (@em constructor) \g<m> (\g<name>, \g<n>) */ vlib_config_function_runtime_t _vlib_config_function_\g<name>"),
+    # Search for CLIB_PAD_FROM_TO(...); and replace with padding
+    # #define CLIB_PAD_FROM_TO(from,to) u8 pad_##from[(to) - (from)]
+    ( re.compile("(?P<m>CLIB_PAD_FROM_TO)\s*[(](?P<from>[^,]+),\s*(?P<to>[^)]+)[)]"),
+        r"/** Padding. */ u8 pad_\g<from>[(\g<to>) - (\g<from>)]" ),
 
-    # Search for "format_thing" and "unformat_thing" when used as a function pointer and add parens
-    ( re.compile("(?P<pre>(^|,)\s*)(?P<name>(un)?format_[a-zA-Z0-9_]+)(?P<post>\s*(,|$))") , r"\g<pre>\g<name>()\g<post>" ),
 ]
 
 
diff --git a/doxygen/filter_h.py b/doxygen/filter_h.py
new file mode 100755
index 00000000..967388d5
--- /dev/null
+++ b/doxygen/filter_h.py
@@ -0,0 +1,53 @@
+#!/usr/bin/env python
+# Copyright (c) 2016 Comcast Cable Communications Management, LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Filter for .c files to make various preprocessor tricks Doxygenish
+
+import os, sys, re
+
+if len(sys.argv) < 2:
+    sys.stderr.write("Usage: %s <filename>\n" % (sys.argv[0]))
+    sys.exit(1)
+
+replace_patterns = [
+    # Search for CLIB_PAD_FROM_TO(...); and replace with padding
+    # #define CLIB_PAD_FROM_TO(from,to) u8 pad_##from[(to) - (from)]
+    ( re.compile("(?P<m>CLIB_PAD_FROM_TO)\s*[(](?P<from>[^,]+),\s*(?P<to>[^)]+)[)]"),
+        r"/** Padding. */ u8 pad_\g<from>[(\g<to>) - (\g<from>)]" ),
+
+]
+
+
+filename = sys.argv[1]
+cwd = os.getcwd()
+if filename[0:len(cwd)] == cwd:
+    filename = filename[len(cwd):]
+    if filename[0] == "/":
+        filename = filename[1:]
+
+with open(filename) as fd:
+    line_num = 0
+
+    for line in fd:
+        line_num += 1
+        str = line[:-1] # filter \n
+
+        # Look for search/replace patterns
+        for p in replace_patterns:
+            str = p[0].sub(p[1], str)
+
+        sys.stdout.write(str+"\n")
+
+# All done
diff --git a/vnet/vnet/interface_cli.c b/vnet/vnet/interface_cli.c
index 7b9f5458..654edcaa 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/lookup.h b/vnet/vnet/ip/lookup.h
index fcd080a4..dcc9d25f 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 0d7b4686..d84e8ed1 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 3e5d3954..dbf9df56 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 24ec6f4e..3d1b54fc 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 2b66c6a6..a2ca64b6 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 13102552..5a176088 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>
@@ -68,7 +68,7 @@ u8 * format_ipsec_gre_rx_trace (u8 * s, va_list * args)
  *
  * @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 490a08f2..ddbe934a 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
@@ -175,7 +175,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
@@ -224,7 +224,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]
 */
@@ -279,7 +279,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]
 */
@@ -333,7 +333,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]
 */
@@ -388,7 +388,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]
 */
@@ -443,7 +443,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]
 */
@@ -496,11 +496,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,
@@ -573,7 +577,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]
 */
@@ -689,7 +693,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 221db9ab..2038dce2 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 4275e884..97620bfb 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 0654fe29..05df2a01 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 4950b23a..8fa355e0 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 5c39b797..24cb31fb 100644
--- a/vnet/vnet/l2/l2_input.c
+++ b/vnet/vnet/l2/l2_input.c
@@ -490,7 +490,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)
 {
@@ -500,7 +500,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)
 {
@@ -536,10 +536,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
@@ -771,7 +771,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]
  */
@@ -847,7 +847,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>
  */
@@ -897,7 +897,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>
  */
@@ -936,6 +936,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_input_classify.c b/vnet/vnet/l2/l2_input_classify.c
index 1b9f911c..69cd113d 100644
--- a/vnet/vnet/l2/l2_input_classify.c
+++ b/vnet/vnet/l2/l2_input_classify.c
@@ -21,13 +21,14 @@
 
 /**
  * @file
- * @brief L2 input classifier
+ * @brief L2 input classifier.
  *
- * See also .../vnet/vnet/classify/vnet_classify.[ch]
+ * @sa @ref vnet/vnet/classify/vnet_classify.c
+ * @sa @ref vnet/vnet/classify/vnet_classify.h
  */
 
 /**
- * @brief l2_input_classifier packet trace record
+ * @brief l2_input_classifier packet trace record.
  */
 typedef struct
 {
@@ -42,7 +43,7 @@ typedef struct
 } l2_input_classify_trace_t;
 
 /**
- * @brief vlib node runtime
+ * @brief vlib node runtime.
  */
 typedef struct
 {
@@ -52,7 +53,7 @@ typedef struct
   l2_input_classify_main_t *l2cm;
 } l2_input_classify_runtime_t;
 
-/** packet trace format function */
+/** Packet trace format function. */
 static u8 *
 format_l2_input_classify_trace (u8 * s, va_list * args)
 {
@@ -66,7 +67,7 @@ format_l2_input_classify_trace (u8 * s, va_list * args)
   return s;
 }
 
-/** l2 input classifier main data structure */
+/** l2 input classifier main data structure. */
 l2_input_classify_main_t l2_input_classify_main;
 
 vlib_node_registration_t l2_input_classify_node;
@@ -106,19 +107,19 @@ static char *l2_input_classify_error_strings[] = {
  * @em Uses:
  * - <code>(l2_input_classify_runtime_t *)
  *         rt->classify_table_index_by_sw_if_index</code>
- *	   Head of the per-interface, perprotocol classifier table chain
- * 	   for a specific interface. ~0 => send pkts to the next
- * 	   feature in the L2 feature chain.
+ *	- Head of the per-interface, per-protocol classifier table chain
+ * 	  for a specific interface.
+ *      - @c ~0 => send pkts to the next feature in the L2 feature chain.
  * - <code>vnet_buffer(b)->sw_if_index[VLIB_RX]</code>
  * 	- Indicates the @c sw_if_index value of the interface that the
- * 	packet was received on.
- * - <code>vnet_buffer (b0)->l2.feature_bitmap</code>
+ * 	  packet was received on.
+ * - <code>vnet_buffer(b0)->l2.feature_bitmap</code>
  * 	- Used to steer packets across l2 features enabled on the interface
  * - <code>(vnet_classify_entry_t) e0->next_index</code>
  *	- Used to steer traffic when the classifier hits on a session
  * - <code>(vnet_classify_entry_t) e0->advance</code>
  *	- Signed quantity applied via <code>vlib_buffer_advance</code>
- * 	when the classifier hits on a session
+ * 	  when the classifier hits on a session
  * - <code>(vnet_classify_table_t) t0->miss_next_index</code>
  *	- Used to steer traffic when the classifier misses
  *
@@ -477,7 +478,7 @@ VLIB_REGISTER_NODE (l2_input_classify_node) = {
 VLIB_NODE_FUNCTION_MULTIARCH (l2_input_classify_node,
 			      l2_input_classify_node_fn);
 
-/** l2 input classsifier feature initialization */
+/** l2 input classsifier feature initialization. */
 clib_error_t *
 l2_input_classify_init (vlib_main_t * vm)
 {
@@ -505,7 +506,7 @@ l2_input_classify_init (vlib_main_t * vm)
 VLIB_INIT_FUNCTION (l2_input_classify_init);
 
 
-/** enable/disable l2 input classification on a specific interface */
+/** Enable/disable l2 input classification on a specific interface. */
 void
 vnet_l2_input_classify_enable_disable (u32 sw_if_index, int enable_disable)
 {
@@ -513,7 +514,7 @@ vnet_l2_input_classify_enable_disable (u32 sw_if_index, int enable_disable)
 			      (u32) enable_disable);
 }
 
-/** @brief Set l2 per-protocol, per-interface input classification tables
+/** @brief Set l2 per-protocol, per-interface input classification tables.
  *
  *  @param sw_if_index  interface handle
  *  @param ip4_table_index  ip4 classification table index, or ~0
diff --git a/vnet/vnet/l2/l2_learn.c b/vnet/vnet/l2/l2_learn.c
index 30f5617f..96d4816e 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 8bc43744..85678caf 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 4597d42e..94a4d66b 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_output_classify.c b/vnet/vnet/l2/l2_output_classify.c
index 1cb8b850..c04df3c2 100644
--- a/vnet/vnet/l2/l2_output_classify.c
+++ b/vnet/vnet/l2/l2_output_classify.c
@@ -12,18 +12,16 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-/*
- * l2_classify.c
- */
 
 #include <vnet/l2/l2_classify.h>
 #include <vnet/api_errno.h>
 
 /**
  * @file
- * @brief L2 input classifier
+ * @brief L2 input classifier.
  *
- * See also .../vnet/vnet/classify/vnet_classify.[ch]
+ * @sa @ref vnet/vnet/classify/vnet_classify.c
+ * @sa @ref vnet/vnet/classify/vnet_classify.h
  */
 
 typedef struct
@@ -46,7 +44,7 @@ typedef struct
   l2_output_classify_main_t *l2cm;
 } l2_output_classify_runtime_t;
 
-/** packet trace format function */
+/** Packet trace format function. */
 static u8 *
 format_l2_output_classify_trace (u8 * s, va_list * args)
 {
@@ -61,7 +59,7 @@ format_l2_output_classify_trace (u8 * s, va_list * args)
   return s;
 }
 
-/** l2 output classifier main data structure */
+/** l2 output classifier main data structure. */
 l2_output_classify_main_t l2_output_classify_main;
 
 vlib_node_registration_t l2_output_classify_node;
@@ -477,7 +475,7 @@ VLIB_REGISTER_NODE (l2_output_classify_node) = {
 VLIB_NODE_FUNCTION_MULTIARCH (l2_output_classify_node,
 			      l2_output_classify_node_fn);
 
-/** l2 output classsifier feature initialization */
+/** l2 output classsifier feature initialization. */
 clib_error_t *
 l2_output_classify_init (vlib_main_t * vm)
 {
@@ -507,7 +505,7 @@ l2_output_classify_init (vlib_main_t * vm)
 
 VLIB_INIT_FUNCTION (l2_output_classify_init);
 
-/** enable/disable l2 input classification on a specific interface */
+/** Enable/disable l2 input classification on a specific interface. */
 void
 vnet_l2_output_classify_enable_disable (u32 sw_if_index, int enable_disable)
 {
@@ -516,15 +514,15 @@ vnet_l2_output_classify_enable_disable (u32 sw_if_index, int enable_disable)
 			       (u32) enable_disable);
 }
 
-/** @brief Set l2 per-protocol, per-interface output classification tables
+/** @brief Set l2 per-protocol, per-interface output classification tables.
  *
- *  @param sw_if_index  interface handle
- *  @param ip4_table_index  ip4 classification table index, or ~0
- *  @param ip6_table_index  ip6 classification table index, or ~0
+ *  @param sw_if_index        interface handle
+ *  @param ip4_table_index    ip4 classification table index, or ~0
+ *  @param ip6_table_index    ip6 classification table index, or ~0
  *  @param other_table_index  non-ip4, non-ip6 classification table index,
  *         or ~0
  *  @returns 0 on success, VNET_API_ERROR_NO_SUCH_TABLE, TABLE2, TABLE3
- *  if the indicated (non-~0) table does not exist.
+ *           if the indicated (non-~0) table does not exist.
  */
 
 int
diff --git a/vnet/vnet/l2/l2_vtr.c b/vnet/vnet/l2/l2_vtr.c
index 6250074e..3ec8b8a7 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 95219e6e..344a8b96 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/tuntap.c b/vnet/vnet/unix/tuntap.c
index 83e7ec4f..b3fbc7f3 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/vppinfra/vppinfra/bihash_template.c b/vppinfra/vppinfra/bihash_template.c
index a8d095c9..2ad82930 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 07c3e7da..a8bb27ff 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