Creating Doxygen documentation for a new library

1. All supporting files were created with Doxygen version 1.8.20. Please download from https://sourceforge.net/projects/doxygen/files/rel-1.8.20/.

2. Your library API should have each function, data type, and constant documented according to the Doxygen format using @brief and @param. Doxygen will output warnings if you are missing this. Please see the MQTT library for example documentation. An example function:

   /**
    * @brief Function description.
    *
    * @param[in] input An input parameter.
    * @param[out] output An output parameter.
    *
    * @return List of values returned.
    *
    * <b>Example</b>
    * @code{c}
    * status = MyFunction(input, output);
    * @endcode
    */
   /* @[declare_mylibrary_myfunction] */
   size_t MyLibrary_MyFunction( size_t input, size_t * output );
   /* @[declare_mylibrary_myfunction] */
   

3. Your library must have a @file command and @brief description in each file for Doxygen to know to parse the file as part of the library. Please see the MQTT library for examples. An example from mqtt.h:

   /**
    * @file mqtt.h
    * @brief User-facing functions of the MQTT 3.1.1 library.
    */
   

4. Please associate each data type and constant in your library's public API to a group so that it will appear in the custom Doxygen pages. For each comment block add the following commands to associate your data types and constants:

   Data Type	Command
   constant	@ingroup <library_name>_constants
   function pointer	@ingroup <library_name>_callback_types
   enum	@ingroup <library_name>_enum_types
   struct	@ingroup <library_name>_struct_types

   Some examples of grouped data types and constants in mqtt.h:

   /**
    * @ingroup mqtt_constants
    * @brief Invalid packet identifier.
    *
    * Zero is an invalid packet identifier as per MQTT v3.1.1 spec.
    */
   #define MQTT_PACKET_ID_INVALID    ( ( uint16_t ) 0U )
   
   /**
    * @ingroup mqtt_callback_types
    * @brief Application provided callback to retrieve the current time in
    * milliseconds.
    *
    * @return The current time in milliseconds.
    */
   typedef uint32_t (* MQTTGetCurrentTimeFunc_t )( void );
   
   /**
    * @ingroup mqtt_enum_types
    * @brief Values indicating if an MQTT connection exists.
    */
   typedef enum MQTTConnectionStatus
   {
       MQTTNotConnected, /**< @brief MQTT Connection is inactive. */
       MQTTConnected     /**< @brief MQTT Connection is active. */
   } MQTTConnectionStatus_t;
   
   /**
    * @ingroup mqtt_struct_types
    * @brief An element of the state engine records for QoS 1 or Qos 2 publishes.
    */
   typedef struct MQTTPubAckInfo
   {
       uint16_t packetId;               /**< @brief The packet ID of the original PUBLISH. */
       MQTTQoS_t qos;                   /**< @brief The QoS of the original PUBLISH. */
       MQTTPublishState_t publishState; /**< @brief The current state of the publish process. */
   } MQTTPubAckInfo_t;
   

5. Please add /* @[declare_<function name>] */ around each API function so that Doxygen can copy the function signature to custom function pages.

   /* @[declare_mylibrary_myfunction] */
   size_t MyLibrary_MyFunction( size_t input, size_t * output );
   /* @[declare_mylibrary_myfunction] */
   

6. Please copy the all of the template pages to your library's docs/doxygen folder. For our CI to detect files correctly, please keep the folder name as docs/doxygen and all of the files names the same.

   cp -R <csdk_root>/docs/doxygen_templates <library_root>/docs/doxygen
   

7. Search for "FIXME"s in <library_root>/docs/doxygen/config.doxygen and update with your library information.

8. Search for "FIXME"s in <library_root>/docs/doxygen/pages.txt and update with your library's information.

9. Add your library to the CSDK's list of libraries, in the first section in <csdk_root>/docs/doxygen/pages.txt.

   - [<library_name>](@ref library_name) - [<library_repo_name>](<library_repo_github_url>)
   

10. Add the name of your library's Doxygen TAG file to the list of library tag files in <csdk_root>/docs/doxygen/config.doxyfile configuration option named TAGFILES:

    TAGFILES               = <csdk_path_to_library>/docs/doxygen/output/<library_name>.tag=../../../../<csdk_path_to_library>/docs/doxygen/output/html
    

11. Generate Doxygen with the current working directory as the root of your library's repo:

    doxygen docs/doxygen/config.doxygen
    

    Fix all warnings.

12. Generate Doxygen in the CSDK repo root:

    git submodule update --init --checkout
    python tools/doxygen/generate_docs.py --root .
    

    Fix all warnings.