[boost] doxygen limitations

Subject: [boost] doxygen limitations
From: Vicente BOTET (vicente.botet_at_[hidden])
Date: 2011-03-30 18:34:39

Hi,

I would like to comment some limitations I have found while trying to generate the reference manual from the code comments using doxygen.

1. C++0x explicit operators are not documented as explicit with a warning

explicit operator underlying_type const&() const 
^^^^
gives

operator underlying_type const &() const;

2. ::type misplaced when inheriting from a metafunction

template <
typename Final,
typename UT,
typename MetaMixinSeq=boost::mpl::vector0<>,
typename Base=base_opaque_type
>
class new_class : public linear_hierarchy::type
{

gives

template, 
typename Base = base_opaque_type> 
class new_class : public linear_hierarchy::type< MetaMixinSeq, Final, Base > {
// ^^^^ 

3. The base type is missing if the class is not documented elsewhere. 
This applies to other classes defined in other libraries in Boost or the Stl, but also when we use parameterized inheritance.

template 
struct inherited_from_underlying
{
template 
struct type : Base { // Parameterized inheritance

};
};

gives

template 
struct inherited_from_underlying {
// member classes/structs/unions
template 
struct type {
};
};

4. When the brief comment takes only one line the comment is included on the Synopsis and nothing on the description section

//! the underlying type
typedef UT underlying_type;

generates

typedef UT underlying_type; // the underlying type

5. The classes are sometimes implicitly prefixed with his namespace

template <
typename UT,
typename Tag=void,
typename Bool=bool,
typename MetaMixinSeq=boost::mpl::vector0<>,
typename Base=base_private_opaque_type
>
class private_opaque_type : public
private_opaque_class< private_opaque_type,
UT, Bool, MetaMixinSeq, Base>

gives

template, 
typename Base = base_private_opaque_type> 
class private_opaque_type : public boost::opaque::private_opaque_class< private_opaque_type< UT, Tag, Bool, MetaMixinSeq, Base >, UT, Bool, MetaMixinSeq, Base >

Do you have a workaround to some of these issues?

What about creating a specific doxygen limitations and workarounds wiki page?

Is there a possibility that the generated html goes to a single reference html file?

Best,
Vicente

P.S. You can see directly some real examples on the documentation of Boost.Opaque https://svn.boost.org/svn/boost/sandbox/opaque/libs/opaque/doc/html/index.html.