From d4024f586216a6bf4e2dfb667df8149b7f95b5c6 Mon Sep 17 00:00:00 2001
From: Chris Luke <chrisy@flirble.org>
Date: Tue, 6 Sep 2016 09:32:36 -0400
Subject: VPP-346 More VPP doc fixes

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

Change-Id: Ia8cca545e5de9f8750602bffa3c4548acc8971aa
Signed-off-by: Chris Luke <chrisy@flirble.org>
---
 vlib/vlib/buffer.c           | 8 ++++++++
 vlib/vlib/buffer_funcs.h     | 4 ++--
 vlib/vlib/counter.h          | 4 ++--
 vlib/vlib/dpdk_buffer.c      | 8 ++++++++
 vlib/vlib/vlib_process_doc.h | 6 +++---
 5 files changed, 23 insertions(+), 7 deletions(-)

(limited to 'vlib')

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
-- 
cgit 1.2.3-korg