Message du 23/03/11 13:28 De : "barend" A : boost@lists.boost.org 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