nasa / cFE

The Core Flight System (cFS) Core Flight Executive (cFE)
Apache License 2.0
402 stars 197 forks source link

Add group name to doxygen "close section" command #1272

Open astrogeco opened 3 years ago

astrogeco commented 3 years ago

Is your feature request related to a problem? Please describe. Keeping track of large doxygen sections can be hard.

/** @defgroup CFEAPISBZeroCopy cFE Zero Copy APIs
 * @{
 */

/*****************************************************************************/
/**
** \brief Get a buffer pointer to use for "zero copy" SB sends.
**
** \par Description
**          This routine can be used to get a pointer to one of the software bus'
**          internal memory buffers that are used for sending messages.  The caller
**          can use this memory buffer to build an SB message, then send it using
**          the CFE_SB_TransmitBuffer() function.  This interface avoids an extra
**          copy of the message from the user's memory buffer to the software bus
**          internal buffer.
**
** \par Assumptions, External Events, and Notes:
**          -# The pointer returned by CFE_SB_AllocateMessageBuffer() is only good for one
**             call to CFE_SB_TransmitBuffer().
**          -# Once a buffer has been successfully transmitted (as indicated by a successful
**             return from CFE_SB_TransmitBuffer()) the buffer becomes owned by the SB application.
**             It will automatically be freed by SB once all recipients have finished reading it.
**          -# Applications must not de-reference the message pointer (for reading
**             or writing) after the call to CFE_SB_TransmitBuffer().
**
** \param[in]  MsgSize  The size of the SB message buffer the caller wants
**                      (including the SB message header).
**
** \return A pointer to a memory buffer that message data can be written to
**         for use with CFE_SB_TransmitBuffer().
**/
CFE_SB_Buffer_t *CFE_SB_AllocateMessageBuffer(size_t MsgSize);

... 

/** @} */

Describe the solution you'd like Add the section name to the closing comment, similar to what we already do for #endif segments.


/** @defgroup CFEAPISBZeroCopy cFE Zero Copy APIs
 * @{
 */

...

/** @} CFEAPISBZeroCopy */

Describe alternatives you've considered Leave as is

jphickey commented 3 years ago

Experience dictates that as code inside/around these blocks changes, the start/end tags will get out of sync very quickly (e.g. look at all the header wrapper #endif comments that had to be fixed by #1262).

IMO a wrong comment is worse than no comment at all.