Proposal for Updating Doxygen Comments within OpenAMP for Consistent Documentation of Data Structures - Openamp-system-reference

16 Mar 2023


      Hello All,
As per the discussion last week in the OpenAMP System Reference call, here is my proposal for updating the Doxygen comments for data structures.  I would like to target these changes for the April 2023 release.
Existing problems with data structure documentation formatting:
------------------------------------------------------------------------------------
1 - Data structure member descriptions are not being generated in documentation
2 - In place where description should be, there is only a line number and file reference
Proposed changes for structure updates:
-----------------------------------------------------
1- Update OpenAMP code to add Doxygen comments for member descriptions to display properly.
Current definition of rpmsg_endpoint:
++++++++++++++++++++++++++++
/**
 * struct rpmsg_endpoint - binds a local rpmsg address to its user
 * @name: name of the service supported
 * @rdev: pointer to the rpmsg device
 * @addr: local address of the endpoint
 * @dest_addr: address of the default remote endpoint binded.
 * @cb: user rx callback, return value of this callback is reserved
 *      for future use, for now, only allow RPMSG_SUCCESS as return value.
 * @ns_unbind_cb: end point service unbind callback, called when remote
 *                ept is destroyed.
 * @node: end point node.
 * @priv: private data for the driver's use
 *
 * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as
 * it binds an rpmsg address with an rx callback handler.
 */
struct rpmsg_endpoint {
    char name[RPMSG_NAME_SIZE];
    struct rpmsg_device *rdev;
    uint32_t addr;
    uint32_t dest_addr;
    rpmsg_ept_cb cb;
    rpmsg_ns_unbind_cb ns_unbind_cb;
    struct metal_list node;
    void *priv;
};
Proposed updates to rpmsg_endpoint:
+++++++++++++++++++++++++++++
Comment descriptions should be column-aligned.  Copy/paste caused problems.
/**
 * struct rpmsg_endpoint - binds a local rpmsg address to its user
 *
 * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as
 * it binds an rpmsg address with an rx callback handler.
 */
struct rpmsg_endpoint {
    char name[RPMSG_NAME_SIZE];       /** Name of the service supported */
    struct rpmsg_device *rdev;        /** Pointer to the rpmsg device */
    uint32_t addr;                    /** Local address of the endpoint */
    uint32_t dest_addr;               /** Address of the default remote endpoint binded */
    rpmsg_ept_cb cb;                  /** User rx callback, return value of this callback is reserved
                                              for future use, for now, only allow RPMSG_SUCCESS as return value */
    rpmsg_ns_unbind_cb ns_unbind_cb;  /** Endpoint service unbind callback, called when remote ept is destroyed */
    struct metal_list node;           /** Endpoint node */
    void *priv;                       /** Private data for the driver's use */
};
2 - Update Doxyfile to remove line number / file from description
-------------------------------------------------------------------------------------
Updates to Doxyfile to remove line number reference from data structure parameters:
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# If the SOURCE_BROWSER tag is set to YES then a list of source files will be
# generated. Documented entities will be cross-referenced with these sources.
#
# Note: To get rid of all source code in the generated output, make sure that
# also VERBATIM_HEADERS is set to NO.
# The default value is: NO.
SOURCE_BROWSER         = NO