Page MenuHomeClusterLabs Projects

Multi-line PCMK__OUTPUT_ARGS breaks doxygen
Open (Needs Information), WishlistPublic

Assigned To
Authored By
Jan 28 2024, 6:53 PM
  • Restricted Project
  • Restricted Project
  • Restricted Project
Referenced Files


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 *")
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
 * ...
                  "const xmlNode *")
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.

Event Timeline

nrwahl2 triaged this task as Wishlist priority.Jan 28 2024, 6:53 PM
nrwahl2 created this task.
nrwahl2 created this object with edit policy "Restricted Project (Project)".
nrwahl2 updated the task description. (Show Details)
nrwahl2 added a project: Restricted Project.Jan 28 2024, 7:11 PM

I assume you are building without -DPCMK__WITH_ATTRIBUTE_OUTPUT_ARGS, right? In that case, PCMK__OUTPUT_ARGS is defined to nothing. So, that's weird.

It looks like doxygen implements its own C source scanner. I wonder if it has issues with variadic macros.

clumens changed the task status from Open to Needinfo.May 16 2024, 4:25 PM

I'm not exactly sure what I'm supposed to be seeing in the API docs, but with the following patch applied:

diff --git a/doc/ b/doc/
index 7f9720e61..40b52a418 100644
--- a/doc/
+++ b/doc/
@@ -795,7 +795,7 @@ EXCLUDE_PATTERNS       =
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories use the pattern */test/*
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include

the only place PCMK__OUTPUT_ARGS appears is in _source.html files. So perhaps that's the fix?