Doxygen - no detailed description for functions in namespaces

Question

I'm trying to get doxygen 1.8.7 to include detailed descriptions in the HTML output. For example, given the following file:

/** \file iniparse.h */

namespace ini {
/** \brief A brief description.
 *
 * A longer description.
 */
inline void parse() {}
}

My HTML for iniparse.h contains an entry for ini::parse, with text "A brief description. More..." The "More..." part is a broken link to a non-existent anchor in the same page. And the text "A longer description" appears nowhere in the generated HTML.

If I get rid of the namespace and just define a function parse (i.e., ::parse) outside of any namespace, things work fine. Can someone tell me how to get the same behavior inside a namespace? Thanks.

Answer 1

Turns out this problem is caused by a combination of three things. First, a plain old bug in doxygen:

https://bugzilla.gnome.org/show_bug.cgi?id=745481

Second, even with the bug fix, you need to generate the namespaces page or you still get broken links. Hence, you need to have SHOW_NAMESPACES = YES in your Doxyfile.

Third, unless you have EXTRACT_ALL = YES, you have to make sure the namespace itself is documented by attaching a Doxygen comment to it. So you need:

//! The ini namespace
namespace ini {
...
}

On one hand maybe it makes sense to require namespaces to be documented if you want documentation for their contents. However, it's weird that doxygen shows the first part of the documentation even without the namespace documentation. So I would argue this is still kind of a bug, but at least I know how to work around it now.