Proposal for Updating Doxygen Comments within OpenAMP for Consistent Documentation of Data Structures
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
Hi Tammy,
As discussed during meeting LGTM I have just a suggestion on the way of documenting the structure ( inspired from Zephyr) My comment in line
ST Restricted
-----Original Message----- From: Leino, Tammy via Openamp-system-reference <openamp-system- reference@lists.openampproject.org> Sent: Thursday, March 16, 2023 6:37 PM To: openamp-system-reference@lists.openampproject.org Subject: [OA-syst-ref] Proposal for Updating Doxygen Comments within OpenAMP for Consistent Documentation of Data Structures
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 updates: - use @brief ? to check if relevant vs your proposal - move field description on a separate line before the field ( more readable in the source code)
/** * @brief structure that 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 { ]; /** Name of the service supported */ char name[RPMSG_NAME_SIZE
/** Pointer to the rpmsg device */ struct rpmsg_device *rdev;
/** Local address of the endpoint */ uint32_t addr;
/** Address of the default remote endpoint binded */ uint32_t dest_addr;
/** User rx callback, return value of this callback is reserved * for future use, for now, only allow RPMSG_SUCCESS * as return value */ rpmsg_ept_cb cb;
/** Endpoint service unbind * callback, called when remote ept is destroyed */ rpmsg_ns_unbind_cb ns_unbind_cb;
/** Endpoint node */ struct metal_list node;
/** Private data for the driver's use */ void *priv; };
Thanks, Arnaud
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
-- Openamp-system-reference mailing list -- openamp-system- reference@lists.openampproject.org To unsubscribe send an email to openamp-system-reference- leave@lists.openampproject.org
openamp-system-reference@lists.openampproject.org
-
Arnaud POULIQUEN -
Leino, Tammy