Message du 23/03/11 08:32 De : "Barend Gehrels" A : boost@lists.boost.org 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