"New API In version A.B.C" page in doxygen

Question

There is a Doxygen option to specify when API appeared using \since tag, for example

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

And it would appear in foo()'s documentation.

What I'm looking is a way to create automatically page that contains all API appeared in 1.5 - i.e. list all API marked by \since 1.5 or probably some other tag if available.

Edit: I tried to use \ingroup and create a group page containing all new API there and it works. But it moves description to this page, for example moves a new method from class definition to a page "New in 1.2.3" which isn't what I wanted.

Answer 1

You want to create an external reference to the current item, an \xrefitem:

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

All items that share the same <key> will be shown on a special generated page. The <heading> will be used to start a section at the place you're using \xrefitem, whereas <list title> will be used as a title for the resulting page (see remarks below). The text can be arbitrary.

The result you get 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 dots:

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 have to 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 dots, you can of course simplify the alias even more. This will give you two new commands:

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

In both cases, the label must only contain alphanumeric symbols, the version can be arbitrary. If you don't provide the custom text, "Introduced in this version" will be shown.

If there's a page with the identifier version_changes<label>, the list of changes will be added. Note that the \page's title will overwrite the title given by the \xrefitem, which can be handy for major releases.

Example

Here's an example of \sinceversion's usage. Note that you probably want to use another alias like ALIASES += since_vXYZ{1}="\sinceversion{X_Y_Z,X.Y.Z,\1}" if you document a lot of changes for version x.y.z:

Example code

/** 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
 */

List of version change pages

List of changes per version

List of changes per version with additional description

Appearance of changes in function documentation