New @commands

[lawmurray]

Consider this issue a place for new @command requests. Please reply with suggested new commands or requests for existing Doxygen commands that would help with migration of an existing codebase (e.g. @copydoc).

[zyphlar]

Unable to use Doxide in a large existing project because even if I find-replace all these missing commands I still get stuck on this head-scratcher... an @ sign followed by a newline? Ultimately I can't make all these changes to my codebase, I need Doxide to be more forgiving about unknown commands.

error: unrecognized token starting: @

 * @retval kStatus_Success  

I also get thousands of warnings like this, which make me think that even if I got Doxide to build the result would be garbled:

warning: parse failed at 'uint32_t'
note: attempting recovery by erasing '__STATIC_FORCEINLINE'

New @commands:

• Arbitrary @ signs in comments: error: unrecognized token starting: @ 3 GHz
• @addtogroup
• @{
• @}
• @name
• @date
• @version
• all other supported Doxygen commands / at least don't error on them

[lawmurray]

Thanks for the report @zyphlar, this is helpful. To go through your issues:

1. error: unrecognized token starting: @. This is a bug. Fix for you in 29b2e16 and new release on the way. That should get you past the error I think.

2. Thousands of warnings. Yes, Doxide could do with a --quiet option or different levels of verbosity (I'll add a ticket for this), but if you can get past the annoyance this may be just noise. It's Doxide reporting autocorrection of perceived syntax errors that arise from preprocessor macros. An explanation of what's going on, and how to silence the warnings. If you grep for recovery failed you'll see if there is actually an error parsing that could not be autocorrected, otherwise it's all just friendly chatter.

3. New commands. Suggestions noted. By way of workarounds... Sections (e.g. @name, @{, @}) I can't think of a workaround within the current feature set. Groups (e.g. @addtogroup) are handled a little differently in Doxide, so you can use the @ingroup style at least. For @date and @version the workaround would be just formatting as you please in Markdown.

[zyphlar]

It might be worth adding a custom command section to the YML, I kept trying to do

  defines:
    date: "Date: "
    version: "Version: "

to get things working, and that could be a stopgap to having to implement every single command.

As for groups, I don't think we'll be able to redo all our docs to specify groups in YML and @ingroup every single entity unfortunately, so maybe using Doxide will have to wait on that for us. (We use ad-hoc groups to organize library header files into more readable topic guides, and it would be crappy to have to centrally manage that in a second place rather than keeping all related documentation in one file, trusting that some in-file @command is enough to properly update the docs)