VPP-288: Documentation changes via doxygen for vnet/vnet/l2.

Change-Id: I55b552fd054610c993d14078ce048c8c4b676104
Signed-off-by: Billy McFall <bmcfall@redhat.com>

14 files changed, 564 insertions, 53 deletions

diff --git a/vnet/vnet/l2/dir.dox b/vnet/vnet/l2/dir.dox
new file mode 100644
index 00000000000..8497a2f64cc
--- /dev/null
+++ b/vnet/vnet/l2/dir.dox
@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2013 Cisco and/or its affiliates.
+ *
+ * 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.
+ */
+
+/**
+@dir
+@brief Layer 2 Forwarding Code.
+
+This directory contains the source code for basic Layer 2 forwarding.
+
+*/
+/*? %%clicmd:group_label Layer 2 CLI %% ?*/
diff --git a/vnet/vnet/l2/l2_bd.c b/vnet/vnet/l2/l2_bd.c
index ddbe934abeb..0b5656e6d2c 100644
--- a/vnet/vnet/l2/l2_bd.c
+++ b/vnet/vnet/l2/l2_bd.c
@@ -32,6 +32,14 @@
 #include <vppinfra/hash.h>
 #include <vppinfra/vec.h>
 
+/**
+ * @file
+ * @brief Ethernet Bridge Domain.
+ *
+ * Code in this file manages Layer 2 bridge domains.
+ *
+ */
+
 bd_main_t bd_main;
 
 /**
@@ -270,6 +278,17 @@ done:
   return error;
 }
 
+/*?
+ * Layer 2 learning can be enabled and disabled on each
+ * interface and on each bridge-domain. Use this command to
+ * manage bridge-domains. It is enabled by default.
+ *
+ * @cliexpar
+ * Example of how to enable learning (where 200 is the bridge-domain-id):
+ * @cliexcmd{set bridge-domain learn 200}
+ * Example of how to disable learning (where 200 is the bridge-domain-id):
+ * @cliexcmd{set bridge-domain learn 200 disable}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (bd_learn_cli, static) = {
   .path = "set bridge-domain learn",
@@ -324,6 +343,18 @@ done:
   return error;
 }
 
+
+/*?
+ * Layer 2 unicast forwarding can be enabled and disabled on each
+ * interface and on each bridge-domain. Use this command to
+ * manage bridge-domains. It is enabled by default.
+ *
+ * @cliexpar
+ * Example of how to enable forwarding (where 200 is the bridge-domain-id):
+ * @cliexcmd{set bridge-domain forward 200}
+ * Example of how to disable forwarding (where 200 is the bridge-domain-id):
+ * @cliexcmd{set bridge-domain forward 200 disable}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (bd_fwd_cli, static) = {
   .path = "set bridge-domain forward",
@@ -379,6 +410,17 @@ done:
   return error;
 }
 
+/*?
+ * Layer 2 flooding can be enabled and disabled on each
+ * interface and on each bridge-domain. Use this command to
+ * manage bridge-domains. It is enabled by default.
+ *
+ * @cliexpar
+ * Example of how to enable flooding (where 200 is the bridge-domain-id):
+ * @cliexcmd{set bridge-domain flood 200}
+ * Example of how to disable flooding (where 200 is the bridge-domain-id):
+ * @cliexcmd{set bridge-domain flood 200 disable}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (bd_flood_cli, static) = {
   .path = "set bridge-domain flood",
@@ -434,6 +476,17 @@ done:
   return error;
 }
 
+/*?
+ * Layer 2 unknown-unicast flooding can be enabled and disabled on each
+ * bridge-domain. It is enabled by default.
+ *
+ * @cliexpar
+ * Example of how to enable unknown-unicast flooding (where 200 is the
+ * bridge-domain-id):
+ * @cliexcmd{set bridge-domain uu-flood 200}
+ * Example of how to disable unknown-unicast flooding (where 200 is the bridge-domain-id):
+ * @cliexcmd{set bridge-domain uu-flood 200 disable}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (bd_uu_flood_cli, static) = {
   .path = "set bridge-domain uu-flood",
@@ -486,6 +539,16 @@ done:
   return error;
 }
 
+/*?
+ * Modify whether or not an existing bridge-domain should terminate and respond
+ * to ARP Requests. ARP Termination is disabled by default.
+ *
+ * @cliexpar
+ * Example of how to enable ARP termination (where 200 is the bridge-domain-id):
+ * @cliexcmd{set bridge-domain arp term 200}
+ * Example of how to disable ARP termination (where 200 is the bridge-domain-id):
+ * @cliexcmd{set bridge-domain arp term 200 disable}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (bd_arp_term_cli, static) = {
   .path = "set bridge-domain arp term",
@@ -579,7 +642,7 @@ bd_add_del_ip_mac (u32 bd_index,
 /**
     Set bridge-domain arp entry add/delete.
     The CLI format is:
-    set bridge-domain arp entry <bd-id> <ip-addr> <mac-addr> [del]
+    set bridge-domain arp entry <bridge-domain-id> <ip-addr> <mac-addr> [del]
 */
 static clib_error_t *
 bd_arp_entry (vlib_main_t * vm,
@@ -649,10 +712,19 @@ done:
   return error;
 }
 
+/*?
+ * Add an ARP entry to an existing bridge-domain.
+ *
+ * @cliexpar
+ * Example of how to add an ARP entry (where 200 is the bridge-domain-id):
+ * @cliexcmd{set bridge-domain arp entry 200 192.168.72.45 52:54:00:3b:83:1a}
+ * Example of how to delete an ARP entry (where 200 is the bridge-domain-id):
+ * @cliexcmd{set bridge-domain arp entry 200 192.168.72.45 52:54:00:3b:83:1a del}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (bd_arp_entry_cli, static) = {
   .path = "set bridge-domain arp entry",
-  .short_help = "set bridge-domain arp entry <bd-id> <ip-addr> <mac-addr> [del]",
+  .short_help = "set bridge-domain arp entry <bridge-domain-id> <ip-addr> <mac-addr> [del]",
   .function = bd_arp_entry,
 };
 /* *INDENT-ON* */
@@ -844,6 +916,31 @@ done:
   return error;
 }
 
+/*?
+ * Show a summary of all the bridge-domain instances or detailed view of a
+ * single bridge-domain. Bridge-domains are created by adding an interface
+ * to a bridge using the '<em>set interface l2 bridge</em>' command.
+ *
+ * @cliexpar
+ * @parblock
+ * Example of displaying all bridge-domains:
+ * @cliexstart{show bridge-domain}
+ *  ID   Index   Learning   U-Forwrd   UU-Flood   Flooding   ARP-Term     BVI-Intf
+ *  0      0        off        off        off        off        off        local0
+ * 200     1        on         on         on         on         off          N/A
+ * @cliexend
+ *
+ * Example of displaying details of a single bridge-domains:
+ * @cliexstart{show bridge-domain 200 detail}
+ *  ID   Index   Learning   U-Forwrd   UU-Flood   Flooding   ARP-Term     BVI-Intf
+ * 200     1        on         on         on         on         off          N/A
+ *
+ *          Interface           Index  SHG  BVI        VLAN-Tag-Rewrite
+ *  GigabitEthernet0/8/0.200      3     0    -               none
+ *  GigabitEthernet0/9/0.200      4     0    -               none
+ * @cliexend
+ * @endparblock
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (bd_show_cli, static) = {
   .path = "show bridge-domain",
diff --git a/vnet/vnet/l2/l2_efp_filter.c b/vnet/vnet/l2/l2_efp_filter.c
index 2038dce2737..2db4dc69c9c 100644
--- a/vnet/vnet/l2/l2_efp_filter.c
+++ b/vnet/vnet/l2/l2_efp_filter.c
@@ -26,6 +26,21 @@
 #include <vppinfra/error.h>
 #include <vppinfra/cache.h>
 
+/**
+ * @file
+ * @brief EFP-filter - Ethernet Flow Point Filter.
+ *
+ * It is possible to transmit a packet out a subinterface with VLAN tags
+ * that are not compatible with that subinterface. In other words, if that
+ * packet arrived on the output port, it would not be classified as coming
+ * from the output subinterface. This can happen in various ways: through
+ * misconfiguration, by putting subinterfaces with different VLAN encaps in
+ * the same bridge-domain, etc. The EFP Filter Check detects such packets
+ * and drops them. It consists of two checks, one that verifies the packet
+ * prior to output VLAN tag rewrite and one that verifies the packet after
+ * VLAN tag rewrite.
+ *
+ */
 typedef struct
 {
 
@@ -568,6 +583,19 @@ done:
 }
 
 
+/*?
+ * EFP filtering is a basic switch feature which prevents an interface from
+ * transmitting a packet that doesn't match the interface's ingress match
+ * criteria. The check has two parts, one performed before egress vlan tag
+ * rewrite and one after. This command enables or disables the EFP filtering
+ * for a given sub-interface.
+ *
+ * @cliexpar
+ * Example of how to enable a Layer 2 efp-filter on a sub-interface:
+ * @cliexcmd{set interface l2 efp-filter GigabitEthernet0/8/0.200}
+ * Example of how to disable a Layer 2 efp-filter on a sub-interface:
+ * @cliexcmd{set interface l2 efp-filter GigabitEthernet0/8/0.200 disable}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (int_l2_efp_filter_cli, static) = {
   .path = "set interface l2 efp-filter",
diff --git a/vnet/vnet/l2/l2_fib.c b/vnet/vnet/l2/l2_fib.c
index 97620bfba6b..20546763669 100644
--- a/vnet/vnet/l2/l2_fib.c
+++ b/vnet/vnet/l2/l2_fib.c
@@ -30,6 +30,16 @@
 
 #include <vppinfra/bihash_template.c>
 
+/**
+ * @file
+ * @brief Ethernet MAC Address FIB Table Management.
+ *
+ * The MAC Address forwarding table for bridge-domains is called the l2fib.
+ * Entries are added automatically as part of mac learning, but MAC Addresses
+ * entries can also be added manually.
+ *
+ */
+
 typedef struct
 {
 
@@ -198,6 +208,27 @@ show_l2fib (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * This command dispays the MAC Address entries of the L2 FIB table.
+ * Output can be filtered to just get the number of MAC Addresses or display
+ * each MAC Address for all bridge domains or just a single bridge domain.
+ *
+ * @cliexpar
+ * Example of how to display the number of MAC Address entries in the L2
+ * FIB table:
+ * @cliexstart{show l2fib}
+ * 3 l2fib entries
+ * @cliexend
+ * Example of how to display all the MAC Address entries in the L2
+ * FIB table:
+ * @cliexstart{show l2fib verbose}
+ *     Mac Address     BD Idx           Interface           Index  static  filter  bvi  refresh  timestamp
+ *  52:54:00:53:18:33    1      GigabitEthernet0/8/0.200      3       0       0     0      0         0
+ *  52:54:00:53:18:55    1      GigabitEthernet0/8/0.200      3       1       0     0      0         0
+ *  52:54:00:53:18:77    1                 N/A                -1      1       1     0      0         0
+ * 3 l2fib entries
+ * @cliexend
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (show_l2fib_cli, static) = {
   .path = "show l2fib",
@@ -239,10 +270,21 @@ clear_l2fib (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * This command clears all the MAC Address entries from the L2 FIB table.
+ *
+ * @cliexpar
+ * Example of how to clear the L2 FIB Table:
+ * @cliexcmd{clear l2fib}
+ * Example to show the L2 FIB Table has been cleared:
+ * @cliexstart{show l2fib verbose}
+ * no l2fib entries
+ * @cliexend
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (clear_l2fib_cli, static) = {
   .path = "clear l2fib",
-  .short_help = "Clear l2fib mac forwarding entries",
+  .short_help = "clear l2fib",
   .function = clear_l2fib,
 };
 /* *INDENT-ON* */
@@ -364,10 +406,37 @@ done:
   return error;
 }
 
+/*?
+ * This command adds a MAC Address entry to the L2 FIB table
+ * of an existing bridge-domain. The MAC Address can be static
+ * or dynamic. This command also allows a filter to be added,
+ * such that packets with given MAC Addresses (source mac or
+ * destination mac match) are dropped.
+ *
+ * @cliexpar
+ * Example of how to add a dynamic MAC Address entry to the L2 FIB table
+ * of a bridge-domain (where 200 is the bridge-domain-id):
+ * @cliexcmd{l2fib add 52:54:00:53:18:33 200 GigabitEthernet0/8/0.200}
+ * Example of how to add a static MAC Address entry to the L2 FIB table
+ * of a bridge-domain (where 200 is the bridge-domain-id):
+ * @cliexcmd{l2fib add 52:54:00:53:18:55 200 GigabitEthernet0/8/0.200 static}
+ * Example of how to add a filter such that a packet with the given MAC
+ * Address will be dropped in a given bridge-domain (where 200 is the
+ * bridge-domain-id):
+ * @cliexcmd{l2fib add 52:54:00:53:18:77 200 filter}
+ * Example of show command of the provisioned MAC Addresses and filters:
+ * @cliexstart{show l2fib verbose}
+ *     Mac Address     BD Idx           Interface           Index  static  filter  bvi  refresh  timestamp
+ *  52:54:00:53:18:33    1      GigabitEthernet0/8/0.200      3       0       0     0      0         0
+ *  52:54:00:53:18:55    1      GigabitEthernet0/8/0.200      3       1       0     0      0         0
+ *  52:54:00:53:18:77    1                 N/A                -1      1       1     0      0         0
+ * 3 l2fib entries
+ * @cliexend
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (l2fib_add_cli, static) = {
   .path = "l2fib add",
-  .short_help = "Add l2fib mac forwarding entry  <mac> <bd-id> filter | <intf> [static | bvi]",
+  .short_help = "l2fib add <mac> <bridge-domain-id> filter | <intf> [static | bvi]",
   .function = l2fib_add,
 };
 /* *INDENT-ON* */
@@ -473,10 +542,47 @@ l2fib_test_command_fn (vlib_main_t * vm,
   return error;
 }
 
+/*?
+ * The set of '<em>test l2fib</em>' commands allow the L2 FIB table of the default
+ * bridge domain (bridge-domain-id of 0) to be modified.
+ *
+ * @cliexpar
+ * @parblock
+ * Example of how to add a set of 4 sequential MAC Address entries to L2
+ * FIB table of the default bridge-domain:
+ * @cliexcmd{test l2fib add mac 52:54:00:53:00:00 count 4}
+ *
+ * Show the set of 4 sequential MAC Address entries that were added:
+ * @cliexstart{show l2fib verbose}
+ *     Mac Address     BD Idx           Interface           Index  static  filter  bvi  refresh  timestamp
+ * 52:54:00:53:00:00    0       GigabitEthernet0/8/0.300     8       0       0     0      0         0
+ * 52:54:00:53:00:01    0       GigabitEthernet0/8/0.300     8       0       0     0      0         0
+ * 52:54:00:53:00:03    0       GigabitEthernet0/8/0.300     8       0       0     0      0         0
+ * 52:54:00:53:00:02    0       GigabitEthernet0/8/0.300     8       0       0     0      0         0
+ * 4 l2fib entries
+ * @cliexend
+ *
+ * Example of how to check that the set of 4 sequential MAC Address
+ * entries were added to L2 FIB table of the default
+ * bridge-domain. Used a count of 5 to produce an error:
+ *
+ * @cliexcmd{test l2fib check mac 52:54:00:53:00:00 count 5}
+ * The output of the check command is in the log files. Log file
+ * location may vary based on your OS and Version:
+ *
+ * <b><em># tail -f /var/log/messages | grep l2fib_test_command_fn</em></b>
+ *
+ * Sep  7 17:15:24 localhost vnet[4952]: l2fib_test_command_fn:446: key 52:54:00:53:00:04 AWOL
+ *
+ * Example of how to delete a set of 4 sequential MAC Address entries
+ * from L2 FIB table of the default bridge-domain:
+ * @cliexcmd{test l2fib del mac 52:54:00:53:00:00 count 4}
+ * @endparblock
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (l2fib_test_command, static) = {
   .path = "test l2fib",
-  .short_help = "test l2fib [del] mac <base-addr> count <nn>",
+  .short_help = "test l2fib [add|del|check] mac <base-addr> count <nn>",
   .function = l2fib_test_command_fn,
 };
 /* *INDENT-ON* */
@@ -565,10 +671,18 @@ done:
   return error;
 }
 
+/*?
+ * This command deletes an existing MAC Address entry from the L2 FIB
+ * table of an existing bridge-domain.
+ *
+ * @cliexpar
+ * Example of how to delete a MAC Address entry from the L2 FIB table of a bridge-domain (where 200 is the bridge-domain-id):
+ * @cliexcmd{l2fib del 52:54:00:53:18:33 200}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (l2fib_del_cli, static) = {
   .path = "l2fib del",
-  .short_help = "Delete l2fib mac forwarding entry  <mac> <bd-id>",
+  .short_help = "l2fib del <mac> <bridge-domain-id>",
   .function = l2fib_del,
 };
 /* *INDENT-ON* */
diff --git a/vnet/vnet/l2/l2_flood.c b/vnet/vnet/l2/l2_flood.c
index 05df2a014d9..5e9881bff9f 100644
--- a/vnet/vnet/l2/l2_flood.c
+++ b/vnet/vnet/l2/l2_flood.c
@@ -30,7 +30,10 @@
 #include <vppinfra/hash.h>
 
 
-/*
+/**
+ * @file
+ * @brief Ethernet Flooding.
+ *
  * Flooding uses the packet replication infrastructure to send a copy of the
  * packet to each member interface. Logically the replication infrastructure
  * expects two graph nodes: a prep node that initiates replication and sends the
@@ -538,6 +541,17 @@ done:
   return error;
 }
 
+/*?
+ * Layer 2 flooding can be enabled and disabled on each
+ * interface and on each bridge-domain. Use this command to
+ * manage interfaces. It is enabled by default.
+ *
+ * @cliexpar
+ * Example of how to enable flooding:
+ * @cliexcmd{set interface l2 flood GigabitEthernet0/8/0}
+ * Example of how to disable flooding:
+ * @cliexcmd{set interface l2 flood GigabitEthernet0/8/0 disable}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (int_flood_cli, static) = {
   .path = "set interface l2 flood",
diff --git a/vnet/vnet/l2/l2_fwd.c b/vnet/vnet/l2/l2_fwd.c
index 8fa355e01a0..586aa3d4206 100644
--- a/vnet/vnet/l2/l2_fwd.c
+++ b/vnet/vnet/l2/l2_fwd.c
@@ -31,6 +31,15 @@
 #include <vppinfra/sparse_vec.h>
 
 
+/**
+ * @file
+ * @brief Ethernet Forwarding.
+ *
+ * Code in this file handles forwarding Layer 2 packets. This file calls
+ * the FIB lookup, packet learning and the packet flooding as necessary.
+ * Packet is then sent to the next graph node.
+ */
+
 typedef struct
 {
 
@@ -454,6 +463,17 @@ done:
   return error;
 }
 
+/*?
+ * Layer 2 unicast forwarding can be enabled and disabled on each
+ * interface and on each bridge-domain. Use this command to
+ * manage interfaces. It is enabled by default.
+ *
+ * @cliexpar
+ * Example of how to enable fowarding:
+ * @cliexcmd{set interface l2 forward GigabitEthernet0/8/0}
+ * Example of how to disable fowarding:
+ * @cliexcmd{set interface l2 forward GigabitEthernet0/8/0 disable}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (int_fwd_cli, static) = {
   .path = "set interface l2 forward",
diff --git a/vnet/vnet/l2/l2_input.c b/vnet/vnet/l2/l2_input.c
index 9b827bad347..dca13e30191 100644
--- a/vnet/vnet/l2/l2_input.c
+++ b/vnet/vnet/l2/l2_input.c
@@ -34,6 +34,17 @@
 #include <vppinfra/hash.h>
 #include <vppinfra/cache.h>
 
+/**
+ * @file
+ * @brief Interface Input Mode (Layer 2 Cross-Connect or Bridge / Layer 3).
+ *
+ * This file contains the CLI Commands that modify the input mode of an
+ * interface. For interfaces in a Layer 2 cross-connect, all packets
+ * received on one interface will be transmitted to the other. For
+ * interfaces in a bridge-domain, packets will be forwarded to other
+ * interfaces in the same bridge-domain based on destination mac address.
+ * For interfaces in Layer 3 mode, the packets will be routed.
+ */
 
 /* Feature graph node names */
 static char *l2input_feat_names[] = {
@@ -838,21 +849,36 @@ done:
   return error;
 }
 
-/* *INDENT-OFF* */
 /*?
+ * Use this command put an interface into Layer 2 bridge domain. If a
+ * bridge-domain with the provided bridge-domain-id does not exist, it
+ * will be created. Interfaces in a bridge-domain forward packets to
+ * other interfaces in the same bridge-domain based on destination mac
+ * address. To remove an interface from a the Layer 2 bridge domain,
+ * put the interface in a different mode, for example Layer 3 mode.
+ *
+ * Optionally, an interface can be added to a Layer 2 bridge-domain as
+ * a Bridged Virtual Interface (bvi). Only one interface in a Layer 2
+ * bridge-domain can be a bvi.
+ *
+ * Optionally, a split-horizon group can also be specified. This defaults
+ * to 0 if not specified.
  *
  * @cliexpar
- * @cliexstart{set interface l2 bridge}
- * Interfaces in a bridge-domain forward packets to other interfaces in the same bridge-domain based on destination mac address.
- * To add an interface to bridge-domain 5 use:
- *  vpp# set interface l2 bridge GigabitEthernet2/0/0 5
- * A split-horizon group can also be specified. This defaults to 0 if not specified.
- *  vpp# set interface l2 bridge GigabitEthernet2/0/0 5 1
- * @cliexend
- ?*/
+ * Example of how to configure a Layer 2 bridge-domain with three
+ * interfaces (where 200 is the bridge-domain-id):
+ * @cliexcmd{set interface l2 bridge GigabitEthernet0/8/0.200 200}
+ * This interface is added a BVI interface:
+ * @cliexcmd{set interface l2 bridge GigabitEthernet0/9/0.200 200 bvi}
+ * This interface also has a split-horizon group of 1 specified:
+ * @cliexcmd{set interface l2 bridge GigabitEthernet0/a/0.200 200 1}
+ * Example of how to remove an interface from a Layer2 bridge-domain:
+ * @cliexcmd{set interface l3 GigabitEthernet0/a/0.200}
+?*/
+/* *INDENT-OFF* */
 VLIB_CLI_COMMAND (int_l2_bridge_cli, static) = {
   .path = "set interface l2 bridge",
-  .short_help = "set interface to L2 bridging mode in <bridge-domain ID> [bvi] [shg]",
+  .short_help = "set interface l2 bridge <interface> <bridge-domain-id> [bvi] [shg]",
   .function = int_l2_bridge,
 };
 /* *INDENT-ON* */
@@ -899,16 +925,22 @@ done:
   return error;
 }
 
-/* *INDENT-OFF* */
 /*?
- * L2 Cross-connect two interfaces
+ * Use this command put an interface into Layer 2 cross-connect mode.
+ * Both interfaces must be in this mode for bi-directioal traffic. All
+ * packets received on one interface will be transmitted to the other.
+ * To remove the Layer 2 cross-connect, put the interface in a different
+ * mode, for example Layer 3 mode.
+ *
  * @cliexpar
- * @cliexstart{set interface l2 xconnect}
- * To cross-connect two interfaces, put both into L2 cross-connect mode. All packets received on one interface will be transmitted to the other.
- *  vpp# set interface l2 xconnect GigabitEthernet2/0/0 GigabitEthernet2/0/1
- *  vpp# set interface l2 xconnect GigabitEthernet2/0/1 GigabitEthernet2/0/0
- * @cliexend
- ?*/
+ * Example of how to configure a Layer2 cross-connect between two interfaces:
+ * @cliexcmd{set interface l2 xconnect GigabitEthernet0/8/0.300 GigabitEthernet0/9/0.300}
+ * @cliexcmd{set interface l2 xconnect GigabitEthernet0/9/0.300 GigabitEthernet0/8/0.300}
+ * Example of how to remove a Layer2 cross-connect:
+ * @cliexcmd{set interface l3 GigabitEthernet0/8/0.300}
+ * @cliexcmd{set interface l3 GigabitEthernet0/9/0.300}
+?*/
+/* *INDENT-OFF* */
 VLIB_CLI_COMMAND (int_l2_xc_cli, static) = {
   .path = "set interface l2 xconnect",
   .short_help = "set interface l2 xconnect <interface> <peer interface>",
@@ -947,19 +979,20 @@ done:
   return error;
 }
 
-/* *INDENT-OFF* */
 /*?
+ * Modify the packet processing mode of the interface to Layer 3, which
+ * implies packets will be routed. This is the default mode of an interface.
+ * Use this command to remove an interface from a Layer 2 cross-connect or a
+ * Layer 2 bridge.
  *
  * @cliexpar
- * @cliexstart{cmd}
- * Interfaces can be set in either L3 (routed) mode or L2 (xconnect or bridged) mode.
- * Interfaces are in L3 mode by default. To return an interface to L3 mode, use:
- *  vpp# set interface l3 GigabitEthernet2/0/0
- * @cliexend
- ?*/
+ * Example of how to set the mode of an interface to Layer 3:
+ * @cliexcmd{set interface l3 GigabitEthernet0/8/0.200}
+?*/
+/* *INDENT-OFF* */
      VLIB_CLI_COMMAND (int_l3_cli, static) = {
   .path = "set interface l3",
-  .short_help = "set interface to L3 mode",
+  .short_help = "set interface l3 <interface>",
   .function = int_l3,
 };
 /* *INDENT-ON* */
@@ -1050,6 +1083,32 @@ done:
   return error;
 }
 
+/*?
+ * Show the packet processing mode (Layer2 xcross-onnect, Layer 2 bridge,
+ * Layer 3 routed) of all interfaces and sub-interfaces, or limit the
+ * output to just the provided list of interfaces and sub-interfaces.
+ * The output shows the mode, the interface, and if the interface is
+ * a member of a bridge, the bridge-domain-id and the split horizen group (shg).
+ *
+ * @cliexpar
+ * Example of displaying the mode of all interfaces:
+ * @cliexstart{show mode}
+ * l3 local0
+ * l3 GigabitEthernet0/8/0
+ * l3 GigabitEthernet0/9/0
+ * l3 GigabitEthernet0/a/0
+ * l2 bridge GigabitEthernet0/8/0.200 bd_id 200 shg 0
+ * l2 bridge GigabitEthernet0/9/0.200 bd_id 200 shg 0
+ * l2 bridge GigabitEthernet0/a/0.200 bd_id 200 shg 0
+ * l2 xconnect GigabitEthernet0/8/0.300 GigabitEthernet0/9/0.300
+ * l2 xconnect GigabitEthernet0/9/0.300 GigabitEthernet0/8/0.300
+ * @cliexend
+ * Example of displaying the mode of a seleted list of interfaces:
+ * @cliexstart{show mode GigabitEthernet0/8/0 GigabitEthernet0/8/0.200}
+ * l3 GigabitEthernet0/8/0
+ * l2 bridge GigabitEthernet0/8/0.200 bd_id 200 shg 0
+ * @cliexend
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (show_l2_mode, static) = {
   .path = "show mode",
diff --git a/vnet/vnet/l2/l2_input_classify.c b/vnet/vnet/l2/l2_input_classify.c
index 69cd113d093..497df192f39 100644
--- a/vnet/vnet/l2/l2_input_classify.c
+++ b/vnet/vnet/l2/l2_input_classify.c
@@ -631,18 +631,16 @@ int_l2_input_classify_command_fn (vlib_main_t * vm,
  * Configure l2 input classification.
  *
  * @cliexpar
- * @cliexstart {set interface l2 input classify intfc <interface-name>
- *	       [ip4-table <index>]
- *	       [ip6-table <index>]
- *	       [other-table <index>]}
+ * @cliexstart{set interface l2 input classify intfc <interface-name> [ip4-table <index>] [ip6-table <index>] [other-table <index>]}
  * @cliexend
+ * @todo This is incomplete. This needs a detailed description and a
+ * practical example.
  ?*/
-
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (int_l2_input_classify_cli, static) = {
   .path = "set interface l2 input classify",
   .short_help =
-  "set interface l2 input classify intfc <int> [ip4-table <n>]\n"
+  "set interface l2 input classify intfc <interface-name> [ip4-table <n>]\n"
   "  [ip6-table <n>] [other-table <n>]",
   .function = int_l2_input_classify_command_fn,
 };
diff --git a/vnet/vnet/l2/l2_learn.c b/vnet/vnet/l2/l2_learn.c
index 96d4816e1e6..e34fe7a83c8 100644
--- a/vnet/vnet/l2/l2_learn.c
+++ b/vnet/vnet/l2/l2_learn.c
@@ -31,7 +31,7 @@
 
 /**
  * @file
- * Ethernet bridge learning.
+ * @brief Ethernet Bridge Learning.
  *
  * Populate the mac table with entries mapping the packet's source mac + bridge
  * domain ID to the input sw_if_index.
@@ -496,6 +496,17 @@ done:
   return error;
 }
 
+/*?
+ * Layer 2 learning can be enabled and disabled on each
+ * interface and on each bridge-domain. Use this command to
+ * manage interfaces. It is enabled by default.
+ *
+ * @cliexpar
+ * Example of how to enable learning:
+ * @cliexcmd{set interface l2 learn GigabitEthernet0/8/0}
+ * Example of how to disable learning:
+ * @cliexcmd{set interface l2 learn GigabitEthernet0/8/0 disable}
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (int_learn_cli, static) = {
   .path = "set interface l2 learn",
diff --git a/vnet/vnet/l2/l2_output_classify.c b/vnet/vnet/l2/l2_output_classify.c
index c04df3c255b..e5c7bd18ae1 100644
--- a/vnet/vnet/l2/l2_output_classify.c
+++ b/vnet/vnet/l2/l2_output_classify.c
@@ -18,7 +18,7 @@
 
 /**
  * @file
- * @brief L2 input classifier.
+ * @brief Layer 2 Output Classifier.
  *
  * @sa @ref vnet/vnet/classify/vnet_classify.c
  * @sa @ref vnet/vnet/classify/vnet_classify.h
@@ -630,21 +630,19 @@ int_l2_output_classify_command_fn (vlib_main_t * vm,
 }
 
 /*?
- * Configure l2 input classification.
+ * Configure Layer 2 output classification.
  *
  * @cliexpar
- * @cliexstart {set interface l2 output classify intfc <interface-name>
- *	       [ip4-table <index>]
- *	       [ip6-table <index>]
- *	       [other-table <index>]}
+ * @cliexstart{set interface l2 output classify intfc <interface-name> [ip4-table <index>] [ip6-table <index>] [other-table <index>]}
  * @cliexend
- ?*/
-
+ * @todo This is incomplete. This needs a detailed description and a
+ * practical example.
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (int_l2_output_classify_cli, static) = {
   .path = "set interface l2 output classify",
   .short_help =
-  "set interface l2 output classify intfc <int> [ip4-table <n>]\n"
+  "set interface l2 output classify intfc <<interface-name>> [ip4-table <n>]\n"
   "  [ip6-table <n>] [other-table <n>]",
   .function = int_l2_output_classify_command_fn,
 };
diff --git a/vnet/vnet/l2/l2_patch.c b/vnet/vnet/l2/l2_patch.c
index cc35d32c824..5d097bb792e 100644
--- a/vnet/vnet/l2/l2_patch.c
+++ b/vnet/vnet/l2/l2_patch.c
@@ -377,11 +377,19 @@ test_patch_command_fn (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * Create or delete a Layer 2 patch.
+ *
+ * @cliexpar
+ * @cliexstart{test l2patch rx <intfc> tx <intfc> [del]}
+ * @cliexend
+ * @todo This is incomplete. This needs a detailed description and a
+ * practical example.
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (test_patch_command, static) = {
     .path = "test l2patch",
-    .short_help =
-    "rx <intfc> tx <intfc> [del]",
+    .short_help = "test l2patch rx <intfc> tx <intfc> [del]",
     .function = test_patch_command_fn,
 };
 /* *INDENT-ON* */
@@ -421,6 +429,15 @@ show_l2patch (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * Show Layer 2 patch entries.
+ *
+ * @cliexpar
+ * @cliexstart{show l2patch}
+ * @cliexend
+ * @todo This is incomplete. This needs a detailed description and a
+ * practical example.
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (show_l2patch_cli, static) = {
   .path = "show l2patch",
diff --git a/vnet/vnet/l2/l2_rw.c b/vnet/vnet/l2/l2_rw.c
index 94096291cd0..c54509d048b 100644
--- a/vnet/vnet/l2/l2_rw.c
+++ b/vnet/vnet/l2/l2_rw.c
@@ -17,6 +17,15 @@
 #include <vnet/l2/feat_bitmap.h>
 #include <vnet/l2/l2_rw.h>
 
+/**
+ * @file
+ * @brief Layer 2 Rewrite.
+ *
+ * Layer 2-Rewrite node uses classify tables to match packets. Then, using
+ * the provisioned mask and value, modfies the packet header.
+ */
+
+
 l2_rw_main_t l2_rw_main;
 
 vlib_node_registration_t l2_rw_node;
@@ -437,6 +446,14 @@ l2_rw_entry_cli_fn (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * Layer 2-Rewrite node uses classify tables to match packets. Then, using
+ * the provisioned mask and value, modfies the packet header.
+ *
+ * @cliexpar
+ * @todo This is incomplete. This needs a detailed description and a
+ * practical example.
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (l2_rw_entry_cli, static) = {
   .path = "l2 rewrite entry",
@@ -501,6 +518,14 @@ l2_rw_interface_cli_fn (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * Layer 2-Rewrite node uses classify tables to match packets. Then, using
+ * the provisioned mask and value, modfies the packet header.
+ *
+ * @cliexpar
+ * @todo This is incomplete. This needs a detailed description and a
+ * practical example.
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (l2_rw_interface_cli, static) = {
   .path = "set interface l2 rewrite",
@@ -528,6 +553,14 @@ l2_rw_show_interfaces_cli_fn (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * Layer 2-Rewrite node uses classify tables to match packets. Then, using
+ * the provisioned mask and value, modfies the packet header.
+ *
+ * @cliexpar
+ * @todo This is incomplete. This needs a detailed description and a
+ * practical example.
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (l2_rw_show_interfaces_cli, static) = {
   .path = "show l2 rewrite interfaces",
@@ -554,6 +587,14 @@ l2_rw_show_entries_cli_fn (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * Layer 2-Rewrite node uses classify tables to match packets. Then, using
+ * the provisioned mask and value, modfies the packet header.
+ *
+ * @cliexpar
+ * @todo This is incomplete. This needs a detailed description and a
+ * practical example.
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (l2_rw_show_entries_cli, static) = {
   .path = "show l2 rewrite entries",
@@ -596,6 +637,14 @@ l2_rw_set_cli_fn (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * Layer 2-Rewrite node uses classify tables to match packets. Then, using
+ * the provisioned mask and value, modfies the packet header.
+ *
+ * @cliexpar
+ * @todo This is incomplete. This needs a detailed description and a
+ * practical example.
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (l2_rw_set_cli, static) = {
   .path = "set bridge-domain rewrite",
diff --git a/vnet/vnet/l2/l2_vtr.c b/vnet/vnet/l2/l2_vtr.c
index 3ec8b8a7d36..9cb0a7e9da3 100644
--- a/vnet/vnet/l2/l2_vtr.c
+++ b/vnet/vnet/l2/l2_vtr.c
@@ -29,6 +29,17 @@
 #include <vppinfra/error.h>
 #include <vlib/cli.h>
 
+/**
+ * @file
+ * @brief Ethernet VLAN Tag Rewrite.
+ *
+ * VLAN tag rewrite provides the ability to change the VLAN tags on a packet.
+ * Existing tags can be popped, new tags can be pushed, and existing tags can
+ * be swapped with new tags. The rewrite feature is attached to a subinterface
+ * as input and output operations. The input operation is explicitly configured.
+ * The output operation is the symmetric opposite and is automatically derived
+ * from the input operation.
+ */
 
 /** Just a placeholder; ensures file is not eliminated by linker. */
 clib_error_t *
@@ -532,6 +543,58 @@ done:
   return error;
 }
 
+/*?
+ * VLAN tag rewrite provides the ability to change the VLAN tags on a packet.
+ * Existing tags can be popped, new tags can be pushed, and existing tags can
+ * be swapped with new tags. The rewrite feature is attached to a subinterface
+ * as input and output operations. The input operation is explicitly configured.
+ * The output operation is the symmetric opposite and is automatically derived
+ * from the input operation.
+ *
+ * <b>POP:</b> For pop operations, the subinterface encapsulation (the vlan
+ * tags specified when it was created) must have at least the number of popped
+ * tags. e.g. the \"pop 2\" operation would be rejected on a single-vlan interface.
+ * The output tag-rewrite operation for pops is to push the specified number of
+ * vlan tags onto the packet. The pushed tag values are the ones in the
+ * subinterface encapsulation.
+ *
+ * <b>PUSH:</b> For push operations, the ethertype is also specified. The
+ * output tag-rewrite operation for pushes is to pop the same number of tags
+ * off the packet. If the packet doesn't have enough tags it is dropped.
+ *
+ *
+ * @cliexpar
+ * @parblock
+ * By default a subinterface has no tag-rewrite. To return a subinterface to
+ * this state use:
+ * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 disable}
+ *
+ * To pop vlan tags off packets received from a subinterface, use:
+ * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 pop 1}
+ * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 pop 2}
+ *
+ * To push one or two vlan tags onto packets received from an interface, use:
+ * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 push dot1q 100}
+ * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 push dot1ad 100 150}
+ *
+ * Tags can also be translated, which is basically a combination of a pop and push.
+ * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 translate 1-1 dot1ad 100}
+ * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 translate 2-2 dot1ad 100 150}
+ * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 translate 1-2 dot1q 100}
+ * @cliexcmd{set interface l2 tag-rewrite GigabitEthernet0/8/0.200 translate 2-1 dot1q 100 150}
+ *
+ * To display the VLAN Tag settings, show the associate bridge-domain:
+ * @cliexstart{show bridge-domain 200 detail}
+ *  ID   Index   Learning   U-Forwrd   UU-Flood   Flooding   ARP-Term     BVI-Intf
+ * 200     1        on         on         on         on         off          N/A
+ *
+ *          Interface           Index  SHG  BVI        VLAN-Tag-Rewrite
+ *  GigabitEthernet0/8/0.200      5     0    -       trans-1-1 dot1ad 100
+ *  GigabitEthernet0/9/0.200      4     0    -               none
+ *  GigabitEthernet0/a/0.200      6     0    -               none
+ * @cliexend
+ * @endparblock
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (int_l2_vtr_cli, static) = {
   .path = "set interface l2 tag-rewrite",
diff --git a/vnet/vnet/l2/l2_xcrw.c b/vnet/vnet/l2/l2_xcrw.c
index 344a8b96506..70610a853d3 100644
--- a/vnet/vnet/l2/l2_xcrw.c
+++ b/vnet/vnet/l2/l2_xcrw.c
@@ -475,11 +475,23 @@ set_l2_xcrw_command_fn (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * Add or delete a Layer 2 to Layer 3 rewrite cross-connect. This is
+ * used to hook Layer 2 interface(s) up to the Layer 3 stack in
+ * arbitrary ways. For example, cross-connect an L2 interface or
+ * (future) bridge to an mpls-o-gre tunnel. Set up the L2 rewrite
+ * string as shown in mpls_gre_rewrite, and use \"mpls-post-rewrite\"
+ * to fix the GRE IP header checksum and length fields.
+ *
+ * @cliexpar
+ * @todo This is incomplete. This needs a detailed description and a
+ * practical example.
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (set_l2_xcrw_command, static) = {
   .path = "set interface l2 xcrw",
   .short_help =
-  "set int l2 xcrw <interface> next <node-name>\n"
+  "set interface l2 xcrw <interface> next <node-name>\n"
   "    [del] [tx-fib-id <id>] [ipv6] rw <hex-bytes>",
   .function = set_l2_xcrw_command_fn,
 };
@@ -555,10 +567,17 @@ show_l2xcrw_command_fn (vlib_main_t * vm,
   return 0;
 }
 
+/*?
+ * Display a Layer 2 to Layer 3 rewrite cross-connect. This is used to
+ * hook Layer 2 interface(s) up to the Layer 3 stack in arbitrary ways.
+ *
+ * @todo This is incomplete. This needs a detailed description and a
+ * practical example.
+?*/
 /* *INDENT-OFF* */
 VLIB_CLI_COMMAND (show_l2xcrw_command, static) = {
   .path = "show l2xcrw",
-  .short_help = "Display L2/L3 rewrite cross-connects",
+  .short_help = "show l2xcrw",
   .function = show_l2xcrw_command_fn,
 };
 /* *INDENT-ON* */