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