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

Subject: Re: [boost] [documentation] doxygen tags and ALIASES.
From: barend (barend_at_[hidden])
Date: 2011-03-23 08:27:21

> I was thinking to some common ALIASES following the C++ standard
schema:
> 
> Requires,
> Effects,
> Returns,
> Postcondition
> Note
>
Remark
> Param
> Example
> Complexity
> Throws

We have many of these.
@return is a standard Doxygen parameter, as is @param and I think
@throws.

Also notes and remarks are standard Doxygen.

The requires
would mean a concept and we (in Boost.Geometry) map this to a concept
column, mapped to a template parameter.

Complexity might be a good
one.

An examples is normally not one line of code but a complete
program, and should not be inside the Doxygen documentation because it
has to be a compiled example, to avoid errors slipping through.

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

This also depends on the tools which you are using to
create QuickBook.