From 426d98f7562d529f8b82f1f224631601472433f7 Mon Sep 17 00:00:00 2001 From: John McNamara Date: Fri, 10 Jul 2015 16:45:21 +0100 Subject: [PATCH] doc: move doxygen section to the doc guidelines 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 Acked-by: Bruce Richardson --- 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 c27fef4140..22f26dd935 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 b58d4aad5b..06eb0c9626 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 `_ 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 `_ 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 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 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 >/dev/null + +* Read the rendered section of the documentation that you have added for correctness, clarity and consistency + with the surrounding text. -- 2.20.1