[dpdk-dev] [PATCH v2 3/3] doc: moved doxygen section to the doc guidelines

[John McNamara]

Moved and refactored the Doxygen guidelines from the Coding Style doc
to the Documentation Guidelines doc. Replaced the existing Doxygen
references with links.

Signed-off-by: John McNamara <john.mcnamara at intel.com>
---
 doc/guides/guidelines/coding_style.rst  | 134 ++------------------------
 doc/guides/guidelines/documentation.rst | 166 ++++++++++++++++++++++++++++++++
 2 files changed, 172 insertions(+), 128 deletions(-)

diff --git a/doc/guides/guidelines/coding_style.rst b/doc/guides/guidelines/coding_style.rst
index c27fef4..22f26dd 100644
--- a/doc/guides/guidelines/coding_style.rst
+++ b/doc/guides/guidelines/coding_style.rst
@@ -1,5 +1,7 @@
-Coding Style
-============
+.. _coding_style:
+
+DPDK Coding Style
+=================
 
 Description
 -----------
@@ -31,7 +33,7 @@ Usual Comments
 ~~~~~~~~~~~~~~
 
 These comments should be used in normal cases.
-To document a public API, a doxygen-like format must be used: refer to Doxygen Documentation.
+To document a public API, a doxygen-like format must be used: refer to :ref:`doxygen_guidelines`.
 
 .. code-block:: c
 
@@ -491,7 +493,7 @@ Prototypes
 * Function prototypes should be listed in a logical order, preferably alphabetical unless there is a compelling reason to use a different ordering.
 * Functions that are used locally in more than one module go into a separate header file, for example, "extern.h".
 * Do not use the ``__P`` macro.
-* Functions that are part of an external API should be documented using Doxygen-like comments above declarations. See the Doxgen documentation topic for details.
+* Functions that are part of an external API should be documented using Doxygen-like comments above declarations. See :ref:`doxygen_guidelines` for details.
 * Functions that are part of the external API must have an ``rte_`` prefix on the function name.
 * Do not use uppercase letters - either in the form of ALL_UPPERCASE, or CamelCase - in function names. Lower-case letters and underscores only.
 * When prototyping functions, associate names with parameter types, for example:
@@ -683,127 +685,3 @@ Control Statements
                  usage();
                  /* NOTREACHED */
          }
-
-Doxygen Documentation
----------------------
-
-The API documentation is automatically generated in the DPDK framework.
-That is why all files that are part of the public API must be documented using Doxygen syntax.
-
-The public API comprises functions of DPDK that can be used by an external application that will use the SDK.
-Only the Doxygen syntax described in the coding rules (this document) should be used in the code.
-All the Doxygen features are described in the Doxygen manual online.
-
-Documenting a Function
-~~~~~~~~~~~~~~~~~~~~~~
-
-All public functions must be documented. The documentation is placed in the header file, above the declaration of the function.
-The definition of the function may be documented, but using standard comments (not in doxygen format).
-The following is an example of function documentation:
-
-.. code-block:: c
-
- /**
-  * Summary here; one sentence on one line (should not exceed 80 chars).
-  *
-  * A more detailed description goes here.
-  *
-  * A blank line forms a paragraph. There should be no trailing white-space
-  * anywhere.
-  *
-  * @param first
-  *   "@param" is a Doxygen directive to describe a function parameter. Like
-  *   some other directives, it takes a term/summary on the same line and a
-  *   description (this text) indented by 2 spaces on the next line. All
-  *   descriptive text should wrap at 80 chars, without going over.
-  *   Newlines are NOT supported within directives; if a newline would be
-  *   before this text, it would be appended to the general description above.
-  * @param second
-  *   There should be no newline between multiple directives (of the same
-  *   type).
-  *
-  * @return
-  *   "@return" is a different Doxygen directive to describe the return value
-  *   of a function, if there is any.
-  */
- int rte_foo(int first, int second)
-
-
-Documenting Files
-~~~~~~~~~~~~~~~~~
-
-Each public file may start with a comment describing what the file does. For example:
-
-.. code-block:: c
-
- /**
-  * @file
-  * This file describes the coding rules of RTE.
-  *
-  * It contains the coding rules of C code, ASM code, reStructured
-  * Text documentation, and of course how to use doxygen to document
-  * public API.
-  */
-
-
-Documenting Constants and Variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Examples:
-
-.. code-block:: c
-
- /**
-  * The definition of a funny TRUE.
-  */
- #define TRUE 0
-
- #define TRUE 1 /**< another way to document a macro */
-
- /**
-  * Frequency of the HPET counter in Hz
-  *
-  * @see rte_eal_hpet_init()
-  */
- extern uint64_t eal_hpet_resolution_hz;
-
-
-Documenting Structures
-~~~~~~~~~~~~~~~~~~~~~~
-
-Public structures should also be documented.
-The ``/**<`` sequence can be used to documented the fields of the structure, as shown in the following example:
-
-.. code-block:: c
-
- /**
-  * Structure describing a memzone, which is a contiguous portions of
-  * physical memory identified by a name.
-  */
- struct rte_memzone {
-
- #define MEMZONE_NAMESIZE 32
-   char name[MEMZONE_NAMESIZE]; /**< name of the memory zone */
-
-   phys_addr_t phys_addr;       /**< start physical address */
-   void *addr;                  /**< start virtual address */
-   uint64_t len;                /**< len of the memzone */
-
-   int socket_id;               /**< NUMA socket id */
- };
-
-
-See Also Sections
-~~~~~~~~~~~~~~~~~
-
-The @see keyword can be used to highlight a link to an existing function, file, or URL.
-This directive should be placed on one line, without anything else, at the bottom of the documentation header.
-
-.. code-block:: c
-
- /**
-  * (documentation of function, file, ...)
-  *
-  * @see rte_foo()
-  * @see eal_memzone.c
-  */
diff --git a/doc/guides/guidelines/documentation.rst b/doc/guides/guidelines/documentation.rst
index b47f028..3ef334b 100644
--- a/doc/guides/guidelines/documentation.rst
+++ b/doc/guides/guidelines/documentation.rst
@@ -577,3 +577,169 @@ Hyperlinks
 
 * The use of a label is preferred since it works across files and will still work if the header text changes.
 
+
+.. _doxygen_guidelines:
+
+Doxygen Guidelines
+------------------
+
+The DPDK API is documented using Doxygen comment annotations in the header files.
+Doxygen is a very powerful tool, it is extremely configurable and with a little effort can be used to create expressive documents.
+See the `Doxygen website <http://www.stack.nl/~dimitri/doxygen/>`_ for full details on how to use it.
+
+The following are some guidelines for use of Doxygen in the DPDK API documentation:
+
+* New libraries that are documented with Doxygen should be added to the Doxygen configuration file: ``doc/api/doxy-api.conf``.
+  It is only required to add the directory that contains the files.
+  It isn't necessary to explicitly name each file since the configuration matches all ``rte_*.h`` files in the directory.
+
+* Use proper capitalization and punctuation in the Doxygen comments since they will become sentences in the documentation.
+  This in particular applies to single line comments, which is the case the is most often forgotten.
+
+* Use ``@`` style Doxygen commands instead of ``\`` style commands.
+
+* Add a general description of each library at the head of the main header files:
+
+  .. code-block:: c
+
+      /**
+       * @file
+       * RTE Mempool.
+       *
+       * A memory pool is an allocator of fixed-size object. It is
+       * identified by its name, and uses a ring to store free objects.
+       * ...
+       */
+
+* Document the purpose of a function, the parameters used and the return
+  value:
+
+  .. code-block:: c
+
+     /**
+      * Attach a new Ethernet device specified by arguments.
+      *
+      * @param devargs
+      *  A pointer to a strings array describing the new device
+      *  to be attached. The strings should be a pci address like
+      *  `0000:01:00.0` or **virtual** device name like `eth_pcap0`.
+      * @param port_id
+      *  A pointer to a port identifier actually attached.
+      *
+      * @return
+      *  0 on success and port_id is filled, negative on error.
+      */
+     int rte_eth_dev_attach(const char *devargs, uint8_t *port_id);
+
+* Doxygen supports Markdown style syntax such as bold, italics, fixed width text and lists.
+  For example the second line in the ``devargs`` parameter in the previous example will be rendered as:
+
+     The strings should be a pci address like ``0000:01:00.0`` or **virtual** device name like ``eth_pcap0``.
+
+* Use ``-`` instead of ``*`` for lists within the Doxygen comment since the latter can get confused with the comment delimiter.
+
+* Add an empty line between the function description, the ``@params`` and ``@return`` for readability.
+
+* Place the ``@params`` description on separate line and indent it by 2 spaces.
+  (It would be better to use no indentation since this is more common and also because checkpatch complains about leading
+  whitespace in comments.
+  However this is the convention used in the existing DPDK code.)
+
+* Documented functions can be linked to simply by adding ``()`` to the function name:
+
+  .. code-block:: c
+
+      /**
+       * The functions exported by the application Ethernet API to setup
+       * a device designated by its port identifier must be invoked in
+       * the following order:
+       *     - rte_eth_dev_configure()
+       *     - rte_eth_tx_queue_setup()
+       *     - rte_eth_rx_queue_setup()
+       *     - rte_eth_dev_start()
+       */
+
+  In the API documentation the functions will be rendered as links, see the
+  `online section of the rte_ethdev.h docs <http://dpdk.org/doc/api/rte__ethdev_8h.html>`_ that contains the above text.
+
+* The ``@see`` keyword can be used to create a *see also* link to another file or library.
+  This directive should be placed on one line at the bottom of the documentation section.
+
+  .. code-block:: c
+
+     /**
+      * ...
+      *
+      * Some text that references mempools.
+      *
+      * @see eal_memzone.c
+      */
+
+* Doxygen supports two types of comments for documenting variables, constants and members: prefix and postfix:
+
+  .. code-block:: c
+
+     /** This is a prefix comment. */
+     #define RTE_FOO_ERROR  0x023.
+
+     #define RTE_BAR_ERROR  0x024. /**< This is a postfix comment. */
+
+* Postfix comments are preferred for struct members and constants if they can be documented in the same way:
+
+  .. code-block:: c
+
+     struct rte_eth_stats {
+         uint64_t ipackets; /**< Total number of received packets. */
+         uint64_t opackets; /**< Total number of transmitted packets.*/
+         uint64_t ibytes;   /**< Total number of received bytes. */
+         uint64_t obytes;   /**< Total number of transmitted bytes. */
+         uint64_t imissed;  /**< Total of RX missed packets. */
+         uint64_t ibadcrc;  /**< Total of RX packets with CRC error. */
+         uint64_t ibadlen;  /**< Total of RX packets with bad length. */
+     }
+
+  Note: postfix comments should be aligned with spaces not tabs in accordance
+  with the :ref:`coding_style`.
+
+* If a single comment type can't be used, due to line length limitations then
+  prefix comments should be preferred.
+  For example this section of the code contains prefix comments, postfix comments on the same line and postfix
+  comments on a separate line:
+
+  .. code-block:: c
+
+     /** Number of elements in the elt_pa array. */
+     uint32_t    pg_num __rte_cache_aligned;
+     uint32_t    pg_shift;     /**< LOG2 of the physical pages. */
+     uintptr_t   pg_mask;      /**< Physical page mask value. */
+     uintptr_t   elt_va_start;
+     /**< Virtual address of the first mempool object. */
+     uintptr_t   elt_va_end;
+     /**< Virtual address of the <size + 1> mempool object. */
+     phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT];
+     /**< Array of physical page addresses for the mempool buffer. */
+
+  This doesn't have an effect on the rendered documentation but it is confusing for the developer reading the code.
+  It this case it would be clearer to use prefix comments throughout:
+
+  .. code-block:: c
+
+     /** Number of elements in the elt_pa array. */
+     uint32_t    pg_num __rte_cache_aligned;
+     /** LOG2 of the physical pages. */
+     uint32_t    pg_shift;
+     /** Physical page mask value. */
+     uintptr_t   pg_mask;
+     /** Virtual address of the first mempool object. */
+     uintptr_t   elt_va_start;
+     /** Virtual address of the <size + 1> mempool object. */
+     uintptr_t   elt_va_end;
+     /** Array of physical page addresses for the mempool buffer. */
+     phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT];
+
+* Check for Doxygen warnings in new code by checking the API documentation build::
+
+     make doc-api-html | grep "warning:"
+
+* Read the rendered section of the documentation that you have added for correctness, clarity and consistency
+  with the surrounding text.
-- 
1.8.1.4