This only affects internal doxygen, which we don't actually produce, hence Wishlist priority.

Suppose we take the patchset_display.c:xml_patchset_default() function, make it non-static, and remove the \internal tag from its doxygen:

/*!
 * \brief Output a user-friendly form of an XML patchset
 *
 * This function parses an XML patchset (an \p XML_ATTR_DIFF element and its
 * children) into a user-friendly combined diff output.
 *
 * \param[in,out] out   Output object
 * \param[in]     args  Message-specific arguments
 *
 * \return Standard Pacemaker return code
 *
 * \note \p args should contain only the XML patchset
 */
PCMK__OUTPUT_ARGS("xml-patchset", "const xmlNode *")
int
xml_patchset_default(pcmk__output_t *out, va_list args)

Then we get the expected documentation in the generated API docs. I would attach screenshots, but Phorge doesn't seem to provide an attachment mechanism. (Edit: Yes it does, with a little "upload file" button in the comment toolbar.)

However, if we split the PCMK__OUTPUT_ARGS over multiple lines, then the generated API docs attach the doxygen to PCMK__OUTPUT_ARGS instead of to xml_patchset_default().

/*!
 * \brief Output a user-friendly form of an XML patchset
 * ...
 */
PCMK__OUTPUT_ARGS("xml-patchset",
                  "const xmlNode *")
int
xml_patchset_default(pcmk__output_t *out, va_list args)

This is problematic when PCMK__OUTPUT_ARGS is very long. Even if we didn't adhere to an 80-character max, some of the line lengths would be outrageous.

As mentioned above, this won't really matter unless we start using PCMK__OUTPUT_ARGS with public functions in the future, but it is annoying to know that it's broken.