Re: [boost] doxygen limitations

Subject: Re: [boost] doxygen limitations
From: Vicente BOTET (vicente.botet_at_[hidden])
Date: 2011-04-15 12:36:10

> Message du 31/03/11 01:47
> De : "Steven Watanabe" 
> A : boost_at_[hidden]
> Copie à : 
> Objet : Re: [boost] doxygen limitations
> 
> 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.

Hi,

Here it is #5478. I have added also two for the support of scoped enums and =default and =delete constructors. 

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

This is odd. How do you manage to document these pattern?

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

Hrrr. Does it mean that these kind of mixin must be documented directly on quickbook?

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

Thanks,

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

Ok, I see.

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

what is onehtml and where it is documented?

Thanks for your help,
Vicente