Message du 31/03/11 01:47 De : "Steven Watanabe" A : boost@lists.boost.org 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

AMDG On 04/16/2011 09:51 AM, Vicente BOTET wrote:

I have started a wiki page compiling the doxygen issue. DOXYGEN/BOOSTBOOK/QUICKBOOK LIMITATIONS AND GUIDELINES

http://svn.boost.org/trac/boost/wiki/Guidelines/DoxygenGuidelines

Please be free to update this with more up to date information, correct incorrect informations, update with better wording, grammar, syntax, ...

For things that look like doxygen bugs, you might consider making minimal test cases that only use doxygen, and reporting it to the doxygen developers. In Christ, Steven Watanabe