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 12:53:37

> Message du 23/03/11 13:28
> De : "barend" 
> A : boost_at_[hidden]
> Copie à : 
> Objet : Re: [boost] [documentation] doxygen tags and ALIASES.
> 
> 
> 
> > 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.

Yes, I know. The question is how to define the missing tags so the look is coherent and the tags are not mixed. As I understand doxygen takes any none tagged line as part of the detailed description (except the first one) and move the tagged lined after the detailed description.

BTW, where can I find the ALIAS you use?

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

I was not only thinking on template parameters requirements but also to run-time requirements (i.e. pre-conditions). the predefined @pre should work if we reach to get a coherent lock.

> 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 was thinking to basic examples, not complete programs. For complete programs I guess we should use reference to external documentation, or is there a better way? 

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

Sorry, I don't understand.

Thanks,
Vicente