Doxygen: @param / @return / @retval / @exception ignored on typdef function pointer

[burningmime]

Easiest way to repro this is to make a file with this:

/**
 * User-provided logging function for displaying informational, warning, or error messages. This function may be called
 * on any thread (and might even be called on multiple threads at once), so be sure to lock appropriately and avoid
 * static data.
 *
 * @param level one of the values of the #semtach_LogLevel enumeration, specifying the importance of the message.
 * @param message a null-terminated string containing the message to write. this buffer is only valid for the length
 *     of the call, so if you plan to use it afterwards, you must make a copy of it.
 */
typedef void(*setmatch_LogCallback)(semtach_LogLevel level, const char* message);

When running dox2html5.py, it gives:

WARNING:root:setmatch_8h.xml: unexpected @param / @return / @retval / @exception found in typedef description, ignoring

[mosra]

Hi,

the Doxygen XML exposes parameters of function pointer typedefs only as a long string, not as separate parameters (so I can't match the @param documentation with the actual parameters) and that's why I'm emitting this warning.

One option is patching Doxygen so it parses and exposes function pointer typedef parameters the same it does for functions. Then I could show the typedefs the same way I'm showing the functions and also correctly match the documentation to each parameter, preserve the order, warn about missing or superfluous ones etc. But someone has to do this, this is one area of Doxygen sources that I'm very afraid to touch :)

Another possibility is just printing the parameter docs in a table, without trying to match them to real parameters. This means no validity checks would be done and it's completely in the full responsibility of the user to ensure the parameters match (meaning, in the example above you could have @param foobar and AFAIK, nothing would complain that it doesn't exist).

[burningmime]

Something would be better than nothing, even if it can't be validated, and even if the order might be wrong. I'd say these are user bugs anyway. Looking at the XML for typedef:

      <memberdef kind="typedef" id="setmatch_8h_1a56e42e8057ff87b6bde14c17e8b50066" prot="public" static="no">
        <type>void(*</type>
        <definition>typedef void(* setmatch_LogCallback) (setmatch_LogLevel level, const char *message)</definition>
        <argsstring>)(setmatch_LogLevel level, const char *message)</argsstring>
        <name>setmatch_LogCallback</name>
<!-- snip -->
<parameternamelist>
<parametername>level</parametername>
</parameternamelist>
<parameterdescription>
<para>one of the values of the #semtach_LogLevel enumeration, specifying the importance of the message. </para></parameterdescription>
</parameteritem>
<parameteritem>
<parameternamelist>
<parametername>message</parametername>
</parameternamelist>
<parameterdescription>
<para>a null-terminated string containing the message to write. this buffer is only valid for the length of the call, so if you plan to use it afterwards, you must make a copy of it. </para></parameterdescription>
</parameteritem>
</parameterlist>

And for an actual function:

<memberdef kind="function" id="setmatch_8h_1a1ac4b223c648a8c882266873c74b8c88" prot="public" static="no" const="no" explicit="no" inline="no" virt="non-virtual">
        <type>void</type>
        <definition>void setmatch_setLogCallback</definition>
        <argsstring>(setmatch_LogCallback logCallback)</argsstring>
        <name>setmatch_setLogCallback</name>
        <param>
          <type><ref refid="setmatch_8h_1a56e42e8057ff87b6bde14c17e8b50066" kindref="member">setmatch_LogCallback</ref></type>
          <declname>logCallback</declname>
        </param>
        <briefdescription>
<para>Sets the log function called by the library when it wants to report something. </para>        </briefdescription>
        <detaileddescription>
<para>If you set this to NULL, the default behaviour of reporting to stdout will be used. Therefore, if you want to suppress all log messages, you must create a no-op function and pass it here.</para><para>This is global and will affect all databases and threads.</para><para><parameterlist kind="param"><parameteritem>
<parameternamelist>
<parametername>logCallback</parametername>
</parameternamelist>
<parameterdescription>
<para>the log function to call. </para></parameterdescription>
</parameteritem>
</parameterlist>

The validation isn't a big concern, but it seems the actual problem is that the types (and type ID references) are missing.

[mosra]

Something would be better than nothing, even if it can't be validated

I agree. Will add this support. I'm quite busy now, so it might take a while. Hope that's okay :)

it seems the actual problem is that the types (and type ID references) are missing

Oh, haha, yes :/ I think the lack of <param> and the type links missing has the same root cause. Possibly related issues -- if any of these would be fixed, then I think m.css can have a ✨ complete ✨ support, including validation:

• Allow for callback parameters to be documented  doxygen/doxygen#6821
• Function pointer wrong behaviour on XML output (Origin: bugzilla #734361) doxygen/doxygen#5542
• Parameters omitted at typedef functions (Origin: bugzilla #674332) doxygen/doxygen#4668