CODEWITHSUNDEEP
c++doxygen
dmedine
dmedine

Reputation: 1555

make a \page and \subpage refer to method documentation in doxygen

I've inherited a C++ project from a colleague who has left the company. In this person's doxygen generated documentation, method documenations are referred to as subpages in the Related Pages tab. This was accomplished through a dummy doxy.h file. Something like this:

/*! \page fooPage foo Functions
 * 
 * - \subpage Copy
 */

Then foo.h would look like this:

/// <summary>   copy a bar </summary>
/// <param name="bar">  bar to copy </param>
/// <returns>copy of bar </returns>
int Copy(int bar);

When I run doxygen -g and doxygen DoxyFile on this setup I get the warning :

warning: unable to resolve reference to 'Copy' for \ref command

although the output also tells me that it has preprocessed and parsed foo.h without error or warning. Then, in the output, foo Functions is an active link under the Related Pages tab (as needed), but Copy is a dead link.

I can get the reference to Copy if I set EXTRACT_ALL = YES but, this isn't what is needed. With EXTRACT_ALL, the documentation for Copy is part of the contents of foo.h in Files and this is what the Copy link in foo Functions points to. I need to exclude the default Files tab from the documentation (mostly because I don't want doxy.h in there).

I can then get rid of the Files tab by generating and editing a layout file, but this isn't quite right either. The Files tab may be gone, but the documentation for Copy is still part of the documentation for foo.h rather than a stand-alone subpage. The documentation for Copy should be a true \subpage of foo Functions, not a link to its documentation in the generated description of foo.h. This is what was required originally and what my former colleague (somehow) accomplished and left behind.

Upvotes: 0

Views: 2150

Answers (1)

albert
albert

Reputation: 9012

As far as I can see with version 1.8.14 and 1.8.18 the link on the related pages is not dead.

From your input I only had to make 1 small change: sdding /// \file on top of the file foo.h.

Most likely the file foo.h is seen but not all information is noted.

The file foo.h would look like:

/// \file


/// <summary>   copy a bar </summary>
/// <param name="bar">  bar to copy </param>
/// <returns>copy of bar </returns>
int Copy(int bar);

Edit 1

I would rather use \ref here and not \subpage

Edit 2

I need to exclude the default Files tab from the documentation

Doxygen has the possibility of steering, in a limited way, the "tabs". Issuing the command: doxygen -l layout_file.xml will create a layout_file.xml a and in the Doxyfile you can refer to this file as:

LAYOUT_FILE =layout_file.xml

In this file there is a line:

<tab type="files" visible="yes" title="">

changing this to

<tab type="files" visible="no" title="">

will remove the tab "files.

See also in the documentation: https://www.doxygen.nl/manual/customize.html#layout

Upvotes: 1

Related Questions