Re: [boost] doxygen limitations

Subject: Re: [boost] doxygen limitations
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2011-03-30 19:45:40

AMDG

On 03/30/2011 03:34 PM, Vicente BOTET wrote:
> 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;
>

Doxygen 1.7 can handle explicit, so
this can be fixed.  Create a trac ticket.
You can assign it to me.

>
> 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>  {
> // ^^^^
>

It's doxygen itself that gets this wrong.

> 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 {
> };
> };
>

Again, doxygen itself loses this.  I don't
know of a workaround.

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

This is intentional and can be controlled by the
BoostBook parameter, boost.compact.typedef.

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

This is done by doxygen.  I suppose that it
would be possible to strip of the unnecessary
namespaces, but if we did that it would happen
regardless of whether the namespace was present
in the source.

>
> 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?
>

You can use onehtml to generate a single html
page.  I don't think this is as well tested as
chunking though.  I believe that the docbook
stylesheets have a bunch of options that allow
you to control chunking, too.

In Christ,
Steven Watanabe