VPP-223 General documentation updates

Per the TWS session...

- Some simple treatment of the contents of pool.h
- Changing some \brief commands to @brief. (will do a more
  complete pass at this later.)

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

3 files changed, 91 insertions, 76 deletions

diff --git a/vlib/vlib/unix/cli.c b/vlib/vlib/unix/cli.c
index 58aa6dfc6bf..e36b80ad990 100644
--- a/vlib/vlib/unix/cli.c
+++ b/vlib/vlib/unix/cli.c
@@ -37,7 +37,7 @@
  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 /**
- * @file vlib/vlib/unix/cli.c
+ * @file
  * @brief Unix stdin/socket command line interface.
  * Provides a command line interface so humans can interact with VPP.
  * This is predominantly a debugging and testing mechanism.
@@ -269,7 +269,7 @@ typedef enum
   UNIX_CLI_PARSE_ACTION_NOMATCH
 } unix_cli_parse_action_t;
 
-/** \brief Mapping of input buffer strings to action values.
+/** @brief Mapping of input buffer strings to action values.
  * @note This won't work as a hash since we need to be able to do
  *       partial matches on the string.
  */
@@ -428,7 +428,7 @@ typedef struct
 static unix_cli_main_t unix_cli_main;
 
 /**
- * \brief Search for a byte sequence in the action list.
+ * @brief Search for a byte sequence in the action list.
  *
  * Searches the @ref unix_cli_parse_actions_t list in @a a for a match with
  * the bytes in @a input of maximum length @a ilen bytes.
@@ -518,7 +518,7 @@ unix_cli_del_pending_output (unix_file_t * uf,
     }
 }
 
-/** \brief A bit like strchr with a buffer length limit.
+/** @brief A bit like strchr with a buffer length limit.
  * Search a buffer for the first instance of a character up to the limit of
  * the buffer length. If found then return the position of that character.
  *
@@ -544,7 +544,7 @@ unix_vlib_findchr (u8 chr, u8 * str, word len)
   return len;
 }
 
-/** \brief Send a buffer to the CLI stream if possible, enqueue it otherwise.
+/** @brief Send a buffer to the CLI stream if possible, enqueue it otherwise.
  * Attempts to write given buffer to the file descriptor of the given
  * Unix CLI session. If that session already has data in the output buffer
  * or if the write attempt tells us to try again later then the given buffer
@@ -582,7 +582,7 @@ unix_vlib_cli_output_raw (unix_cli_file_t * cf,
     }
 }
 
-/** \brief Process a buffer for CRLF handling before outputting it to the CLI.
+/** @brief Process a buffer for CRLF handling before outputting it to the CLI.
  *
  * @param cf Unix CLI session of the desired stream to write to.
  * @param uf The Unix file structure of the desired stream to write to.
@@ -625,7 +625,7 @@ unix_vlib_cli_output_cooked (unix_cli_file_t * cf,
     }
 }
 
-/** \brief Output the CLI prompt */
+/** @brief Output the CLI prompt */
 static void
 unix_cli_cli_prompt (unix_cli_file_t * cf, unix_file_t * uf)
 {
@@ -634,7 +634,7 @@ unix_cli_cli_prompt (unix_cli_file_t * cf, unix_file_t * uf)
   unix_vlib_cli_output_raw (cf, uf, cm->cli_prompt, vec_len (cm->cli_prompt));
 }
 
-/** \brief Output a pager prompt and show number of buffered lines */
+/** @brief Output a pager prompt and show number of buffered lines */
 static void
 unix_cli_pager_prompt (unix_cli_file_t * cf, unix_file_t * uf)
 {
@@ -657,7 +657,7 @@ unix_cli_pager_prompt (unix_cli_file_t * cf, unix_file_t * uf)
   vec_free (prompt);
 }
 
-/** \brief Output a pager "skipping" message */
+/** @brief Output a pager "skipping" message */
 static void
 unix_cli_pager_message (unix_cli_file_t * cf, unix_file_t * uf,
 			char *message, char *postfix)
@@ -673,7 +673,7 @@ unix_cli_pager_message (unix_cli_file_t * cf, unix_file_t * uf,
   vec_free (prompt);
 }
 
-/** \brief Erase the printed pager prompt */
+/** @brief Erase the printed pager prompt */
 static void
 unix_cli_pager_prompt_erase (unix_cli_file_t * cf, unix_file_t * uf)
 {
@@ -695,7 +695,7 @@ unix_cli_pager_prompt_erase (unix_cli_file_t * cf, unix_file_t * uf)
     }
 }
 
-/** \brief Uses an ANSI escape sequence to move the cursor */
+/** @brief Uses an ANSI escape sequence to move the cursor */
 static void
 unix_cli_ansi_cursor (unix_cli_file_t * cf, unix_file_t * uf, u16 x, u16 y)
 {
@@ -1012,7 +1012,7 @@ unix_cli_terminal_type (u8 * term, uword len)
   return 0;
 }
 
-/** \brief Emit initial welcome banner and prompt on a connection. */
+/** @brief Emit initial welcome banner and prompt on a connection. */
 static void
 unix_cli_file_welcome (unix_cli_main_t * cm, unix_cli_file_t * cf)
 {
@@ -1054,7 +1054,7 @@ unix_cli_file_welcome (unix_cli_main_t * cm, unix_cli_file_t * cf)
   cf->started = 1;
 }
 
-/** \brief A failsafe triggered on a timer to ensure we send the prompt
+/** @brief A failsafe triggered on a timer to ensure we send the prompt
  * to telnet sessions that fail to negotiate the terminal type. */
 static void
 unix_cli_file_welcome_timer (any arg, f64 delay)
@@ -1073,7 +1073,7 @@ unix_cli_file_welcome_timer (any arg, f64 delay)
     unix_cli_file_welcome (cm, cf);
 }
 
-/** \brief A mostly no-op Telnet state machine.
+/** @brief A mostly no-op Telnet state machine.
  * Process Telnet command bytes in a way that ensures we're mostly
  * transparent to the Telnet protocol. That is, it's mostly a no-op.
  *
@@ -1201,7 +1201,7 @@ unix_cli_process_telnet (unix_main_t * um,
   return consume;
 }
 
-/** \brief Process actionable input.
+/** @brief Process actionable input.
  * Based on the \c action process the input; this typically involves
  * searching the command history or editing the current command line.
  */
@@ -1883,7 +1883,7 @@ unix_cli_line_process_one (unix_cli_main_t * cm,
   return 1;
 }
 
-/** \brief Process input bytes on a stream to provide line editing and
+/** @brief Process input bytes on a stream to provide line editing and
  * command history in the CLI. */
 static int
 unix_cli_line_edit (unix_cli_main_t * cm,
@@ -1961,7 +1961,7 @@ unix_cli_line_edit (unix_cli_main_t * cm,
   return 1;
 }
 
-/** \brief Process input to a CLI session. */
+/** @brief Process input to a CLI session. */
 static void
 unix_cli_process_input (unix_cli_main_t * cm, uword cli_file_index)
 {
diff --git a/vnet/vnet/ip/ip4_forward.c b/vnet/vnet/ip/ip4_forward.c
index 2ccdd37cbc2..6b7fa9b4d05 100644
--- a/vnet/vnet/ip/ip4_forward.c
+++ b/vnet/vnet/ip/ip4_forward.c
@@ -1039,7 +1039,7 @@ ip4_lookup_inline (vlib_main_t * vm,
   return frame->n_vectors;
 }
 
-/** \brief IPv4 lookup node.
+/** @brief IPv4 lookup node.
     @node ip4-lookup
 
     This is the main IPv4 lookup dispatch node.
@@ -2960,7 +2960,7 @@ ip4_rewrite_inline (vlib_main_t * vm,
 }
 
 
-/** \brief IPv4 transit rewrite node.
+/** @brief IPv4 transit rewrite node.
     @node ip4-rewrite-transit
 
     This is the IPv4 transit-rewrite node: decrement TTL, fix the ipv4
@@ -3000,7 +3000,7 @@ ip4_rewrite_transit (vlib_main_t * vm,
 			     /* rewrite_for_locally_received_packets */ 0);
 }
 
-/** \brief IPv4 local rewrite node.
+/** @brief IPv4 local rewrite node.
     @node ip4-rewrite-local
 
     This is the IPv4 local rewrite node. Fetch the ip adjacency, check
diff --git a/vppinfra/vppinfra/pool.h b/vppinfra/vppinfra/pool.h
index c6235e648d2..186a973107f 100644
--- a/vppinfra/vppinfra/pool.h
+++ b/vppinfra/vppinfra/pool.h
@@ -34,6 +34,12 @@
   OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
   WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
+/** @file
+ * @brief Fixed length block allocator.
+   Pools are built from clib vectors and bitmaps. Use pools when
+   repeatedly allocating and freeing fixed-size data. Pools are
+   fast, and avoid memory fragmentation.
+ */
 
 #ifndef included_pool_h
 #define included_pool_h
@@ -42,27 +48,24 @@
 #include <vppinfra/error.h>
 #include <vppinfra/mheap.h>
 
-/* Pools are built from clib vectors and bitmaps. Use pools when
-   repeatedly allocating and freeing fixed-size data. Pools are
-   fast, and avoid memory fragmentation. */
 
 typedef struct {
-  /* Bitmap of indices of free objects. */
+  /** Bitmap of indices of free objects. */
   uword * free_bitmap;
 
-  /* Vector of free indices.  One element for each set bit in bitmap. */
+  /** Vector of free indices.  One element for each set bit in bitmap. */
   u32 * free_indices;
 } pool_header_t;
 
-/* Align pool header so that pointers are naturally aligned. */
+/** Align pool header so that pointers are naturally aligned. */
 #define pool_aligned_header_bytes \
   vec_aligned_header_bytes (sizeof (pool_header_t), sizeof (void *))
 
-/* Get pool header from user pool pointer */
+/** Get pool header from user pool pointer */
 always_inline pool_header_t * pool_header (void * v)
 { return vec_aligned_header (v, sizeof (pool_header_t), sizeof (void *)); }
 
-/* Validate a pool */
+/** Validate a pool */
 always_inline void pool_validate (void * v)
 {
   pool_header_t * p = pool_header (v);
@@ -93,7 +96,9 @@ do {								\
   pool_header_validate_index ((v), __pool_validate_index);	\
 } while (0)
 
-/* Number of active elements in a pool */
+/** Number of active elements in a pool.
+ * @return Number of active elements in a pool
+ */
 always_inline uword pool_elts (void * v)
 {
   uword ret = vec_len (v);
@@ -102,18 +107,19 @@ always_inline uword pool_elts (void * v)
   return ret;
 }
 
-/* Number of elements in pool vector
+/** Number of elements in pool vector.
 
-    Note: you probably want to call pool_elts() instead
+    @note You probably want to call pool_elts() instead.
 */
 #define pool_len(p)	vec_len(p)
-/* Number of elements in pool vector (usable as an lvalue)
 
-    Note: you probably don't want to use this macro
+/** Number of elements in pool vector (usable as an lvalue)
+
+    @note You probably don't want to use this macro.
 */
 #define _pool_len(p)	_vec_len(p)
 
-/*Memory usage of pool header */
+/** Memory usage of pool header. */
 always_inline uword
 pool_header_bytes (void * v)
 {
@@ -125,13 +131,13 @@ pool_header_bytes (void * v)
   return vec_bytes (p->free_bitmap) + vec_bytes (p->free_indices);
 }
 
-/*Memory usage of pool */
+/** Memory usage of pool. */
 #define pool_bytes(P) (vec_bytes (P) + pool_header_bytes (P))
 
-/*Local variable naming macro. */
+/** Local variable naming macro. */
 #define _pool_var(v) _pool_##v
 
-/*Queries whether pool has at least N_FREE free elements. */
+/** Queries whether pool has at least N_FREE free elements. */
 always_inline uword
 pool_free_elts (void * v)
 {
@@ -148,9 +154,9 @@ pool_free_elts (void * v)
   return n_free;
 }
 
-/* Allocate an object E from a pool P (general version)
+/** Allocate an object E from a pool P (general version).
 
-   First search free list.  If nothing is free extend vector of objects
+   First search free list.  If nothing is free extend vector of objects.
 */
 #define pool_get_aligned(P,E,A)						\
 do {									\
@@ -182,10 +188,10 @@ do {									\
     }									\
 } while (0)
 
-/* Allocate an object E from a pool P (unspecified alignment) */
+/** Allocate an object E from a pool P (unspecified alignment). */
 #define pool_get(P,E) pool_get_aligned(P,E,0)
 
-/* Use free bitmap to query whether given element is free */
+/** Use free bitmap to query whether given element is free. */
 #define pool_is_free(P,E)						\
 ({									\
   pool_header_t * _pool_var (p) = pool_header (P);			\
@@ -193,10 +199,10 @@ do {									\
   (_pool_var (i) < vec_len (P)) ? clib_bitmap_get (_pool_var (p)->free_bitmap, _pool_i) : 1; \
 })
   
-/* Use free bitmap to query whether given index is free */
+/** Use free bitmap to query whether given index is free */
 #define pool_is_free_index(P,I) pool_is_free((P),(P)+(I))
 
-/* Free an object E in pool P */
+/** Free an object E in pool P. */
 #define pool_put(P,E)							\
 do {									\
   pool_header_t * _pool_var (p) = pool_header (P);			\
@@ -210,14 +216,14 @@ do {									\
   vec_add1 (_pool_var (p)->free_indices, _pool_var (l));		\
 } while (0)
 
-/* Free pool element with given index. */
+/** Free pool element with given index. */
 #define pool_put_index(p,i)			\
 do {						\
   typeof (p) _e = (p) + (i);			\
   pool_put (p, _e);				\
 } while (0)
 
-/* Allocate N more free elements to pool (general version) */
+/** Allocate N more free elements to pool (general version). */
 #define pool_alloc_aligned(P,N,A)					\
 do {									\
   pool_header_t * _p;							\
@@ -229,10 +235,10 @@ do {									\
   _vec_len (_p->free_indices) -= (N);					\
 } while (0)
 
-/* Allocate N more free elements to pool (unspecified alignment) */
+/** Allocate N more free elements to pool (unspecified alignment). */
 #define pool_alloc(P,N) pool_alloc_aligned(P,N,0)
 
-/* low-level free pool operator (do not call directly) */
+/** Low-level free pool operator (do not call directly). */
 always_inline void * _pool_free (void * v)
 {
   pool_header_t * p = pool_header (v);
@@ -244,10 +250,10 @@ always_inline void * _pool_free (void * v)
   return 0;
 }
 
-/* Free a pool. */
+/** Free a pool. */
 #define pool_free(p) (p) = _pool_free(p)
 
-/* Optimized iteration through pool 
+/** Optimized iteration through pool.
 
     @param LO pointer to first element in chunk
     @param HI pointer to last element in chunk
@@ -296,34 +302,39 @@ do {									\
     }									\
 } while (0)
 
-/* Iterate through pool 
+/** Iterate through pool.
 
-    @param VAR variable of same type as pool vector
-    @param POOL pool to iterate across
-    @param BODY operation to perform. See the example below.
+    @param VAR A variable of same type as pool vector to be used as an
+               iterator.
+    @param POOL The pool to iterate across.
+    @param BODY The operation to perform, typically a code block. See
+                the example below.
 
-    call BODY with each active pool element.
+    This macro will call @c BODY with each active pool element.
 
-    Example:
-    proc_t *procs;   // a pool of processes <br>
-    proc_t *proc;    // pointer to one process <br>
+    It is a bad idea to allocate or free pool element from within
+    @c pool_foreach. Build a vector of indices and dispose of them later.
 
-    pool_foreach (proc, procs, ({
-    <br>
-    &nbsp;&nbsp;if (proc->state != PROC_STATE_RUNNING)<br>
-    &nbsp;&nbsp;&nbsp;&nbsp;continue;
-    <br>
-    &nbsp;&nbsp;<i>check a running proc in some way</i><br>
-    &nbsp;&nbsp;}));
 
-    It is a bad idea to allocate or free pool element from within
-    pool_foreach. Build a vector of indices and dispose of them later.
+    @par Example
+    @code{.c}
+    proc_t *procs;   // a pool of processes.
+    proc_t *proc;    // pointer to one process; used as the iterator.
 
-    Because pool_foreach is a macro, syntax errors can be difficult to
-    find inside BODY, let alone actual code bugs. One can temporarily
-    split a complex pool_foreach into a trivial pool_foreach which
-    builds a vector of active indices, and a vec_foreach() (or plain
-    for-loop) to walk the active index vector.
+    pool_foreach (proc, procs, ({
+        if (proc->state != PROC_STATE_RUNNING)
+            continue;
+
+        // check a running proc in some way
+        ...
+    }));
+    @endcode
+
+    @warning Because @c pool_foreach is a macro, syntax errors can be
+    difficult to find inside @c BODY, let alone actual code bugs. One
+    can temporarily split a complex @c pool_foreach into a trivial
+    @c pool_foreach which builds a vector of active indices, and a
+    vec_foreach() (or plain for-loop) to walk the active index vector.
  */
 #define pool_foreach(VAR,POOL,BODY)					\
 do {									\
@@ -337,11 +348,14 @@ do {									\
     }));								\
 } while (0)
 
-/* Returns pointer to element at given index
+/** Returns pointer to element at given index.
 
-    ASSERTs that the supplied index is valid. Even though
-    one can write correct code of the form "p = pool_base + index",
-    use of pool_elt_at_index is strongly suggested. 
+    ASSERTs that the supplied index is valid.
+    Even though one can write correct code of the form
+    @code
+        p = pool_base + index;
+    @endcode
+    use of @c pool_elt_at_index is strongly suggested. 
  */
 #define pool_elt_at_index(p,i)			\
 ({						\
@@ -350,7 +364,7 @@ do {									\
   _e;						\
 })
 
-/* Return next occupied pool index after i, useful for safe iteration */
+/** Return next occupied pool index after @c i, useful for safe iteration. */
 #define pool_next_index(P,I)                                            \
 ({                                                                      \
   pool_header_t * _pool_var (p) = pool_header (P);                      \
@@ -363,6 +377,7 @@ do {									\
   _pool_var(rv);                                                        \
 })
 
+/** Iterate pool by index. */
 #define pool_foreach_index(i,v,body)		\
   for ((i) = 0; (i) < vec_len (v); (i)++)	\
     {						\