The "New API in ABC Version" page in doxygen

Question

The "New API in ABC Version" page in doxygen

There is a Doxygen option to indicate when the API appeared with the \since tag, for example

 /// /// Does foo /// /// \since 1.5 /// void foo();

And it will appear in the foo() documentation.

I am looking for a way to automatically create a page containing all the APIs that appeared in 1.5 - i.e. listed all the APIs marked \since 1.5 or possibly some other tags, if available.

Edit: I tried using \ingroup and creating a group page containing all the new APIs and it works. But he moves the description to this page, for example, transfers a new method from the class definition to the "New in 1.2.3" page, which is not what I wanted.

+5

versioning doxygen

Artyom Dec 23 '15 at 11:42

source share

1 answer

Zeta · Accepted Answer · 2015-12-31T11:33:29+0000

You want to create an e x ternal ref binding to the current element , \xrefitem :

 \xrefitem version_change_1_0_0 "Since 1.0.0" "Changes in 1.0.0" ... <key> <heading> <list title> <text>

All elements having the same <key> will be shown on a special generated page. <heading> will be used to launch the section where you use \xrefitem , while <list title> will be used as the title for the resulting page (see Notes below). The text can be arbitrary.

The result is similar to the lists and appearances of \todo and \bug , and you can even think of \bug and \todo implemented as

 \bug <text> = \xrefitem bug "Bug" "List of bugs" <text> \todo <text> = \xrefitem todo "Todo" "List of todos" <text>

Unfortunately, the key cannot contain periods:

 ID "$"?[a-z_A-Z\x80-\xFF][a-z_A-Z0-9\x80-\xFF]* LABELID [a-z_A-Z\x80-\xFF][a-z_A-Z0-9\x80-\xFF\-]*

Therefore, you should use an alias that takes (at least) two arguments, one for the label and one for the actual text:

 ALIASES += sinceversion{3}="\xrefitem version_changes\1 \"Since \2\" \"Changes in \2\" \3\n\n" ALIASES += sinceversion{2}="\sinceversion{\1,\2,Introduced in this version.}"

If you never use periods, you can of course simplify the alias even further. This will give you two new commands:

\sinceversion{label, version}
\sinceversion{label, version, custom text}

In both cases, the label should contain only alphanumeric characters; the version can be arbitrary. If you do not provide custom text, it will show "Introduced in this version."

If there is a page with the identifier version_changes<label> , a list of changes will be added. Note that the \page header will overwrite the header specified by \xrefitem , which may be useful for major releases.

Example

Here is an example of using \sinceversion . Note that you probably want to use a different alias, for example ALIASES += since_vXYZ{1}="\sinceversion{X_Y_Z,XYZ,\1}" if you document a lot of changes for the xyz version:

Code example

 /** Foos around. * \sinceversion{001,0.0.1} */ void foo(){} /** Bars around. * \sinceversion{001,0.0.1} * \sinceversion{002,0.0.2,Removed a memory leak} */ void bar(){} /** \page version_changes002 Changes in 0.0.2 * * We found several memory leaks and removed them */