Re: [boost] [documentation] doxygen tags and ALIASES.

Subject: Re: [boost] [documentation] doxygen tags and ALIASES.
From: Vicente BOTET (vicente.botet_at_[hidden])
Date: 2011-03-23 04:05:36

> Message du 23/03/11 08:32
> De : "Barend Gehrels" 
> A : boost_at_[hidden]
> Copie à : 
> Objet : Re: [boost] [documentation] doxygen tags and ALIASES.
> 
> 
> On 23-3-2011 0:01, Vicente BOTET wrote:
> > I have see that Boost.Local uses some aliases to tag some part of the doxygen documentation.
> > (...)
> > Is somewhere a guideline on how to tag the doxygen documentation for Boost libraries? Is there a list of ALIASES?
> > If not, is there some interest in defining one?
> 
> Boost.Geometry defines a lot (currently 79) of aliases too. However most 
> of them are specific to Boost.Geometry, and I don't see much profit from 
> harmonizing them across libraries (besides the \qbk alias).

I was thinking to some common ALIASES following the C++ standard schema:

Requires,
Effects,
Returns,
Postcondition
Note
Remark
Param
Example
Complexity
Throws

Others can be added:
ExceptionSafety
ThreadSafety

I don't know if my configuration is missing something but I was unable to reference other C++ elements using @see @related or other doxygen tags. When I see the ALIASES Boost.Local uses, I see that there is the definition on how to reference other parts of the doc, but also references to macros, classs using specific aliases
that I was far from thinking it was so complex. SO I guess that some ALIASES could at least share the name.

This not only will help to have uniform look for the reference manual, but also for the code comment themselves.

I would like we share also some PREDEFINED macros that are necessary to get a readable interface.

What is the best way to share this with Boost.Build? Ideas?

> The aliases are used as defining a sort of Domain Specific Documentation 
> Language, to avoid repetitions of the same phrases over and over in the 
> Doxygen sections.

Could you tell me where the geometry ALIASES are defined? I would like to take a look.

Thanks,
Vicente