From e0e7f6f0e76f9193ec431eef4b6f158a19a64c2d Mon Sep 17 00:00:00 2001 From: Eduardo Almeida Date: Mon, 7 Oct 2024 17:23:07 +0100 Subject: [PATCH] doc: Update coding-style to prefer Doxygen @ tags --- doc/contributing/source/coding-style.rst | 41 ++++++++++--------- doc/manual/source/documentation.rst | 52 ++++++++++++------------ 2 files changed, 47 insertions(+), 46 deletions(-) diff --git a/doc/contributing/source/coding-style.rst b/doc/contributing/source/coding-style.rst index f17b91b57..99cc6fdac 100644 --- a/doc/contributing/source/coding-style.rst +++ b/doc/contributing/source/coding-style.rst @@ -683,7 +683,7 @@ is described in the `Doxygen website `_. { /** - * \brief short one-line description of the purpose of your class + * @brief short one-line description of the purpose of your class * * A longer description of the purpose of your class after a blank * empty line. @@ -696,8 +696,8 @@ is described in the `Doxygen website `_. /** * A detailed description of the purpose of the method. * - * \param firstParam a short description of the purpose of this parameter - * \return a short description of what is returned from this function. + * @param firstParam a short description of the purpose of this parameter + * @return a short description of what is returned from this function. */ int DoSomething(int firstParam); @@ -925,9 +925,10 @@ Doxygen comments should use the C-style comment (also known as Javadoc) style. For comments that are intended to not be exposed publicly in the Doxygen output, use the ``@internal`` and ``@endinternal`` tags. Please use the ``@see`` tag for cross-referencing. -All parameters and return values should be documented. The |ns3| codebase uses -both the ``@`` or ``\`` characters for tag identification; please make sure -that usage is consistent within a file. +All parameters and return values should be documented. The |ns3| codebase prefers +the ``@`` character for tag identification. This character is recognized by clang-format +as the start of Doxygen tags, which enables it to keep tags properly formatted; +therefore please don't use ``\`` as the delimiter. .. sourcecode:: cpp @@ -939,7 +940,7 @@ that usage is consistent within a file. /** * Constructor. * - * \param n Number of elements. + * @param n Number of elements. */ MyClass(int n); }; @@ -954,11 +955,11 @@ classes (e.g., all the classes in a module). E.g.; .. sourcecode:: cpp /** - * \defgroup mynewmodule This is a new module + * @defgroup mynewmodule This is a new module */ /** - * \ingroup mynewmodule + * @ingroup mynewmodule * * MyClassOne description. */ @@ -967,7 +968,7 @@ classes (e.g., all the classes in a module). E.g.; }; /** - * \ingroup mynewmodule + * @ingroup mynewmodule * * MyClassTwo description. */ @@ -980,22 +981,22 @@ In the tests for the module, it is suggested to add an ancillary group: .. sourcecode:: cpp /** - * \defgroup mynewmodule-test Tests for new module - * \ingroup mynewmodule - * \ingroup tests + * @defgroup mynewmodule-test Tests for new module + * @ingroup mynewmodule + * @ingroup tests */ /** - * \ingroup mynewmodule-tests - * \brief MyNewModule Test + * @ingroup mynewmodule-tests + * @brief MyNewModule Test */ class MyNewModuleTest : public TestCase { }; /** - * \ingroup mynewmodule-tests - * \brief MyNewModule TestSuite + * @ingroup mynewmodule-tests + * @brief MyNewModule TestSuite */ class MyNewModuleTestSuite : public TestSuite { @@ -1004,7 +1005,7 @@ In the tests for the module, it is suggested to add an ancillary group: }; /** - * \ingroup mynewmodule-tests + * @ingroup mynewmodule-tests * Static variable for test initialization */ static MyNewModuleTestSuite g_myNewModuleTestSuite; @@ -1132,8 +1133,8 @@ The general guidelines are as follows: /** * Receive packet from lower layer (passed to PHY as callback). * - * \param pkt Packet being received. - * \param txMode Mode of received packet. + * @param pkt Packet being received. + * @param txMode Mode of received packet. */ void RxPacketGood(Ptr pkt, double, UanTxMode txMode); diff --git a/doc/manual/source/documentation.rst b/doc/manual/source/documentation.rst index d16108a22..0a55c9771 100644 --- a/doc/manual/source/documentation.rst +++ b/doc/manual/source/documentation.rst @@ -299,17 +299,17 @@ The preferred style for Doxygen comments is the JavaDoc style:: * Explain what the class or method does, using what algorithm. * Explain the units of arguments and return values. * - * \note Note any limitations or gotchas. + * @note Note any limitations or gotchas. * * (For functions with arguments or return valued:) - * \param [in] foo Brief noun phrase describing this argument. Note + * @param [in] foo Brief noun phrase describing this argument. Note * that we indicate if the argument is input, * output, or both. - * \param [in,out] bar Note Sentence case, and terminating period. - * \param [in] baz Indicate boolean values with \c true or \c false. - * \return Brief noun phrase describing the value. + * @param [in,out] bar Note Sentence case, and terminating period. + * @param [in] baz Indicate boolean values with \c true or \c false. + * @return Brief noun phrase describing the value. * - * \internal + * @internal * * You can also discuss internal implementation details. * Understanding this material shouldn't be necessary to using @@ -335,7 +335,7 @@ Some items to note: * Use sentence case, including the initial capital. * Use punctuation, especially \`.'s at the end of sentences or phrases. -* The ``\brief`` tag is not needed; the first sentence will be +* The ``@brief`` tag is not needed; the first sentence will be used as the brief description. Every class, method, typedef, member variable, function argument @@ -522,10 +522,10 @@ usage for |ns3|. * Use Doxygen ``Modules`` to group related items. - In the main header for a module, create a Doxgyen group:: + In the main header for a module, create a Doxygen group:: /** - * \defgroup foo Foo protocol. + * @defgroup foo Foo protocol. * Implementation of the Foo protocol. */ @@ -536,23 +536,23 @@ usage for |ns3|. * Document each file, assigning it to the relevant group. In a header file:: /** - * \file - * \ingroup foo + * @file + * @ingroup foo * Class Foo declaration. */ or in the corresponding ``.cc`` file:: /** - * \file - * \ingroup foo + * @file + * @ingroup foo * Class FooBar implementation. */ * Mark each associated class as belonging to the group:: /** - * \ingroup foo + * @ingroup foo * * FooBar packet type. */ @@ -564,27 +564,27 @@ usage for |ns3|. /** * Bar callback function signature. * - * \param ale The size of a pint of ale, in Imperial ounces. + * @param ale The size of a pint of ale, in Imperial ounces. */ typedef void (* BarCallback)(const int ale); * Copy the ``Attribute`` help strings from the ``GetTypeId`` method to use as the brief descriptions of associated members. -* ``\bugid{298}`` will create a link to bug 298 in our Bugzilla. +* ``@bugid{298}`` will create a link to bug 298 in our Bugzilla. -* ``\p foo`` in a description will format ``foo`` - the same as the ``\param foo`` parameter, making it clear that you +* ``@p foo`` in a description will format ``foo`` + the same as the ``@param foo`` parameter, making it clear that you are referring to an actual argument. -* ``\RFC{301}`` will create a link to RFC 301. +* ``@RFC{301}`` will create a link to RFC 301. -* Document the direction of function arguments with ``\param [in]``, *etc*. +* Document the direction of function arguments with ``@param [in]``, *etc*. The allowed values of the direction token are ``[in]``, ``[out]``, and ``[in,out]`` (note the explicit square brackets), as discussed in the - Doxygen docs for ``\param``. + Doxygen docs for ``@param``. -* Document template arguments with ``\tparam``, just as you use ``\param`` +* Document template arguments with ``@tparam``, just as you use ``@param`` for function arguments. * For template arguments, indicate if they will be deduced or must be given @@ -598,15 +598,15 @@ usage for |ns3|. */ template T Function(U a); - * Use ``\tparam U \deduced`` because the type ``U`` can be deduced at + * Use ``@tparam U @deduced`` because the type ``U`` can be deduced at the site where the template is invoked. Basically deduction can only be done for function arguments. - * Use ``\tparam T \explicit`` because the type ``T`` can't be deduced; + * Use ``@tparam T @explicit`` because the type ``T`` can't be deduced; it must be given explicitly at the invocation site, as in ``Create(...)`` -* ``\internal`` should be used only to set off a discussion of implementation +* ``@internal`` should be used only to set off a discussion of implementation details, not to mark ``private`` functions (they are already marked, as ``private``!) @@ -636,6 +636,6 @@ cases is: /** * Register this type. - * \return The object TypeId. + * @return The object TypeId. */ static TypeId GetTypeId();