Sample plugin: Add sample plugin documentation

Added some user documentation to sample plugin.

Change-Id: I518910f80499307e8fcac8dcef7baaeab5ea8e35
Signed-off-by: Ray Kinsella <ray.kinsella@intel.com>

5 files changed, 92 insertions, 10 deletions

diff --git a/README.md b/README.md
index 7f429d12b31..596494b94f8 100644
--- a/README.md
+++ b/README.md
@@ -45,7 +45,7 @@ Directory name         | Description
 @ref src/vppinfra      | VPP core library
      test              | Unit tests
 @ref src/vpp/api       | Not-yet-relocated API bindings
-
+@ref src/examples      | VPP example code
 
 ## Getting started
 
diff --git a/doxygen/Makefile b/doxygen/Makefile
index abaca185d74..b6ba5887666 100644
--- a/doxygen/Makefile
+++ b/doxygen/Makefile
@@ -74,8 +74,7 @@ DOXY_INPUT := $(subst $(WS_ROOT)/,,$(DOXY_INPUT))
 # These must be left-anchored paths for the regexp below to work.
 DOXY_EXCLUDE ?= \
 	$(DOXY_SRC)/vlib/buffer.c \
-	$(DOXY_SRC)/vpp-api/lua \
-	$(DOXY_SRC)/examples/sample-plugin
+	$(DOXY_SRC)/vpp-api/lua
 
 # Generate a regexp for filenames to exclude
 DOXY_EXCLUDE_REGEXP = ($(subst .,\.,$(shell echo '$(strip $(DOXY_EXCLUDE))' | sed -e 's/ /|/g')))
diff --git a/doxygen/user_doc.md b/doxygen/user_doc.md
index becc2e0a353..c0a05bd96f0 100644
--- a/doxygen/user_doc.md
+++ b/doxygen/user_doc.md
@@ -16,3 +16,4 @@ Several modules provide operational, dataplane-user focused documentation.
 - @subpage span_doc
 - @subpage srv6_doc
 - @subpage srmpls_doc
+- @subpage sample_plugin_doc
diff --git a/src/examples/sample-plugin/sample/sample.c b/src/examples/sample-plugin/sample/sample.c
index 2f8ac4c9857..3929ac23701 100644
--- a/src/examples/sample-plugin/sample/sample.c
+++ b/src/examples/sample-plugin/sample/sample.c
@@ -12,10 +12,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-/*
- *------------------------------------------------------------------
- * sample.c - simple MAC-swap API / debug CLI handling
- *------------------------------------------------------------------
+/**
+ * @file
+ * @brief Sample Plugin, plugin API / trace / CLI handling.
  */
 
 #include <vnet/vnet.h>
@@ -65,7 +64,11 @@ VLIB_PLUGIN_REGISTER () = {
 };
 /* *INDENT-ON* */
 
-/* Action function shared between message handler and debug CLI */
+/**
+ * @brief Enable/disable the macswap plugin. 
+ *
+ * Action function shared between message handler and debug CLI.
+ */
 
 int sample_macswap_enable_disable (sample_main_t * sm, u32 sw_if_index,
                                    int enable_disable)
@@ -135,6 +138,9 @@ macswap_enable_disable_command_fn (vlib_main_t * vm,
   return 0;
 }
 
+/**
+ * @brief CLI command to enable/disable the sample macswap plugin.
+ */
 VLIB_CLI_COMMAND (sr_content_command, static) = {
     .path = "sample macswap",
     .short_help = 
@@ -142,7 +148,9 @@ VLIB_CLI_COMMAND (sr_content_command, static) = {
     .function = macswap_enable_disable_command_fn,
 };
 
-/* API message handler */
+/**
+ * @brief Plugin API message handler.
+ */
 static void vl_api_sample_macswap_enable_disable_t_handler
 (vl_api_sample_macswap_enable_disable_t * mp)
 {
@@ -156,7 +164,9 @@ static void vl_api_sample_macswap_enable_disable_t_handler
   REPLY_MACRO(VL_API_SAMPLE_MACSWAP_ENABLE_DISABLE_REPLY);
 }
 
-/* Set up the API message handling tables */
+/**
+ * @brief Set up the API message handling tables.
+ */
 static clib_error_t *
 sample_plugin_api_hookup (vlib_main_t *vm)
 {
@@ -188,6 +198,9 @@ setup_message_id_table (sample_main_t * sm, api_main_t *am)
 #undef _
 }
 
+/**
+ * @brief Initialize the sample plugin.
+ */
 static clib_error_t * sample_init (vlib_main_t * vm)
 {
   sample_main_t * sm = &sample_main;
@@ -214,6 +227,9 @@ static clib_error_t * sample_init (vlib_main_t * vm)
 
 VLIB_INIT_FUNCTION (sample_init);
 
+/**
+ * @brief Hook the sample plugin into the VPP graph hierarchy.
+ */
 VNET_FEATURE_INIT (sample, static) = 
 {
   .arc_name = "device-input",
diff --git a/src/examples/sample-plugin/sample_plugin_doc.md b/src/examples/sample-plugin/sample_plugin_doc.md
new file mode 100644
index 00000000000..9348094c210
--- /dev/null
+++ b/src/examples/sample-plugin/sample_plugin_doc.md
@@ -0,0 +1,66 @@
+# Sample plugin for VPP    {#sample_plugin_doc}
+
+## Overview
+
+This is the VPP sample plugin demonstrates how to create a new plugin that integrates 
+with VPP. The sample code implements a trival macswap algorithim that demonstrates plugin 
+runtime integration with the VPP graph hierachy, api and cli.
+
+For deeper dive information see the annotations in the  sample code itself. See [sample.c](@ref sample.c)
+
+## How to build and run the sample plugin.
+
+Now (re)build VPP.
+
+	$ make wipe
+
+Define environmental variable 'VPP_WITH_SAMPLE_PLUGIN=yes' with a process scope
+
+	$ VPP_WITH_SAMPLE_PLUGIN=yes make build
+
+or a session scope, and build VPP. 
+
+	$ export VPP_WITH_SAMPLE_PLUGIN=yes
+	& make build
+
+Now run VPP and make sure the plugin is loaded. 
+
+	$ make run
+	...
+	load_one_plugin:184: Loaded plugin: memif_plugin.so (Packet Memory Interface (experimetal))
+	load_one_plugin:184: Loaded plugin: sample_plugin.so (Sample of VPP Plugin)
+	load_one_plugin:184: Loaded plugin: snat_plugin.so (Network Address Translation)
+	...
+	DBGvpp#
+
+## How to create a new plugin
+
+To create a new plugin based on the sample plugin, copy and rename the sample plugin directory and automake config.
+
+	cp -r src/examples/sample-plugin/sample src/plugins/newplugin
+	cp src/examples/sample-plugin/sample.am src/plugins/newplugin.am
+
+Add the following entry to the plugins section of `src/configure.ac`.
+
+	PLUGIN_ENABLED(newplugin)
+
+Add the following entry to the plugins section of `src/plugins/Makefile.am`
+
+	if ENABLE_NEWPLUGIN
+	include newplugin.am
+	endif
+
+Now (re)build VPP.
+
+	$ make wipe
+	$ make build
+
+## Configuration
+
+To enable the sample plugin
+
+	sample macswap <interface name>
+
+To disable the sample plugin
+
+	sample macswap <interface name> disable