[documentation] doxygen tags and ALIASES.
Hi, I have see that Boost.Local uses some aliases to tag some part of the doxygen documentation. ALIASES=" Params=\"Parameters: \" Param{2}=\"\\1\\2 \" EndParams=\"\" Returns=\"Returns:\" Note=\"Note:\" Warning=\"Warning:\" See=\"See:\" RefSect{1}=\"\\xmlonly \\1\\endxmlonly\" RefSect2{2}=\"\\xmlonly \\2\\endxmlonly\" RefClass{1}=\"\\xmlonly\\1\\endxmlonly\" RefMacro{1}=\"\\xmlonly\\1\\endxmlonly\" " For example /** * @brief This macro is used to specify the local function name. * * This macro must follow the local function body code block { ... } as * shown in the @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS} documentation. * * @Params * @Param{name, * The name of the local function. This name cannot be the name of an operator * operator... and it cannot be the same name of another local function * declared within the same enclosing scope (i.e.\, it is not possible to * overload local function declarations) -- see the * @RefSect2{Advanced_Topics\, Advanced Topics} section. * } * @EndParams * * @See @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS}, @RefSect{Tutorial} section, * @RefSect2{Advanced_Topics, Advanced Topics} section. */ Other use html valises directly. //! Effects: //! \code //! for (; first != last; ++result, ++first) //! new (static_cast(&*result)) //! typename iterator_traits::value_type(boost::move(*first)); //! \endcode //! //! Returns: result 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? Thanks, Vicente
On Tue, Mar 22, 2011 at 7:01 PM, Vicente BOTET <vicente.botet@wanadoo.fr> wrote:
Hi,
I have see that Boost.Local uses some aliases to tag some part of the doxygen documentation.
ALIASES=" Params=\"Parameters: \" Param{2}=\"\\1\\2 \" EndParams=\"\" Returns=\"Returns:\" Note=\"Note:\" Warning=\"Warning:\" See=\"See:\" RefSect{1}=\"\\xmlonly \\1\\endxmlonly\" RefSect2{2}=\"\\xmlonly \\2\\endxmlonly\" RefClass{1}=\"\\xmlonly\\1\\endxmlonly\" RefMacro{1}=\"\\xmlonly\\1\\endxmlonly\" "
For example
/** * @brief This macro is used to specify the local function name. * * This macro must follow the local function body code block { ... } as * shown in the @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS} documentation. * * @Params * @Param{name, * The name of the local function. This name cannot be the name of an operator * operator... and it cannot be the same name of another local function * declared within the same enclosing scope (i.e.\, it is not possible to * overload local function declarations) -- see the * @RefSect2{Advanced_Topics\, Advanced Topics} section. * } * @EndParams * * @See @RefMacro{BOOST_LOCAL_FUNCTION_PARAMS}, @RefSect{Tutorial} section, * @RefSect2{Advanced_Topics, Advanced Topics} section. */
Other use html valises directly.
//! Effects: //! \code //! for (; first != last; ++result, ++first) //! new (static_cast(&*result)) //! typename iterator_traits::value_type(boost::move(*first)); //! \endcode //! //! Returns: result
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?
I just recently learned that there was a Boost Documentation project that tried to codify style guidelines, but it appears to be moribund. It's homepage is here: https://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs -- Stirling Westrup Programmer, Entrepreneur. https://www.linkedin.com/e/fpf/77228 http://www.linkedin.com/in/swestrup http://technaut.livejournal.com http://sourceforge.net/users/stirlingwestrup
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). 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. Regards, Barend -- Barend Gehrels http://about.me/barendgehrels
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
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.
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
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.
I'm afraid I don't understand what you're trying to achieve. The doxygen-tags are not meant to give a coherent look, they are meant to generate convenient documentation. So why not mixing tags there?
BTW, where can I find the ALIAS you use?
I sent the doxygen-file-link earlier. In another thread I mentioned the page describing how we document, so I'll repeat that here: http://bit.ly/i2zGfC Is this what you are missing?
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.
Again, of course it looks coherent within Doxygen but the problem is: what to do with that afterwards. We could define a \qbk{[heading Preconditions] The precondion is: foo } Generating a nice looking Quickbook piece. But in the Doxygen-C++ section it does not really look coherent.
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?
Complete programs are the best basic examples. See our example e.g. here: http://bit.ly/en9JsR First I used snippets but Mateusz convinced me that it should really be complete examples including headerfiles. And I agree completely now. This is the same way cplusplus does it , e.g. <http://www.cplusplus.com/reference/algorithm/sort/> which is really useful.
This also depends on the tools which you are using to create QuickBook. Sorry, I don't understand.
I mean, Doxygen-tags themselves are not useful. Doxygen creates HTML-documents which are basically useful but rejected by most Boost folks. But Doxygen can also create XML-documents which can be interpreted by tools as XSLT, or (in our case) a C++/rapidxml implemented tool, which parses the XML and generates QuickBook. From QuickBook you go all the way back to HTML, but that is standard. See also the link I pasted above. Regards, Barend -- Barend Gehrels http://about.me/barendgehrels
AMDG On 03/23/2011 10:44 AM, Barend Gehrels wrote:
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.
Again, of course it looks coherent within Doxygen but the problem is: what to do with that afterwards.
You should be able to handle it in the XML output. I know that doxygen2boostbook handles \pre correctly.
Complete programs are the best basic examples. See our example e.g. here:
First I used snippets but Mateusz convinced me that it should really be complete examples including headerfiles. And I agree completely now.
This is the same way cplusplus does it , e.g.
<http://www.cplusplus.com/reference/algorithm/sort/>
which is really useful.
I usually use quickbook's snippet extraction, and include a link to the actual source. In Christ, Steven Watanabe
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Steven Watanabe Sent: Wednesday, March 23, 2011 6:48 PM To: boost@lists.boost.org Subject: Re: [boost] [documentation] doxygen tags and ALIASES.
AMDG
On 03/23/2011 10:44 AM, Barend Gehrels wrote:
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.
Again, of course it looks coherent within Doxygen but the problem is: what to do with that afterwards.
You should be able to handle it in the XML output. I know that doxygen2boostbook handles \pre correctly.
Complete programs are the best basic examples. See our example e.g. here:
First I used snippets but Mateusz convinced me that it should really be complete examples including headerfiles. And I agree completely now.
This is the same way cplusplus does it , e.g.
<http://www.cplusplus.com/reference/algorithm/sort/>
which is really useful.
I usually use quickbook's snippet extraction, and include a link to the actual source.
I think Steven is right that this is a good combination. The snippet avoids too much irrelevant 'housekeeping' that confuses the important part of the example. And you can mix explanations between several snippets. And the snippets are certain to be what has been compiled (can't get out of sync). But you may need the full example to see all the details, and to try to run it (and perhaps modify it for your purposes). Doxygen has \example but I've not used that in anger yet. I think it includes the whole example file, and is mainly useful if you are looking at the standalone Doxygen format (which has some good aspects), but not so useful if using Quickbook etc. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
Complete programs are the best basic examples. See our example e.g. here: http://bit.ly/en9JsR
First I used snippets but Mateusz convinced me that it should really be complete examples including headerfiles. And I agree completely now.
This is the same way cplusplus does it , e.g.
<http://www.cplusplus.com/reference/algorithm/sort/>
which is really useful. I usually use quickbook's snippet extraction, and include a link to the actual source. I think Steven is right that this is a good combination.
The snippet avoids too much irrelevant 'housekeeping' that confuses the important part of the example.
That is true but... what is normally "irrelevant" or "trivial" for the author, can be a stumbling block for the user. Normally the only thing irrevant is "int main" and (sometimes) headerfiles. Occupying not too much space. All the rest, typedefs, namespace usings or aliases, are relevant housekeeping, which need to be present in examples. Actually I don't see much examples or snippets in Boost doc's. And if there are, they are presented as an example but they are actually a test (e.g., using assert). Therefore, an example including a main (even if that is indeed trivial) and headerfiles is easy to copy and paste. And easy to maintain...
And you can mix explanations between several snippets.
OK, this is possible with examples too. Especially the callouts are useful.
And the snippets are certain to be what has been compiled (can't get out of sync).
But you may need the full example to see all the details, and to try to run it (and perhaps modify it for your purposes).
Then you have it twice... And the example is then normally not syntax highlighted or annotaded, as in Graph. Graph has a lot of useful samples, by the way, but the presentation could just be better. ICL does a good job. Complete examples.
Doxygen has \example but I've not used that in anger yet. I think it includes the whole example file, and is mainly useful if you are looking at the standalone Doxygen format (which has some good aspects), but not so useful if using Quickbook etc.
In the previous version of Boost.Geometry doc's we used: \dontinclude doxygen_1.cpp \skip example_envelope_polygon \line { \until } to extract snippets (indeed). This required much care to extract just the right lines (especially in longer snippets). Now we're using QuickBook example extracting (snippets indeed, but the complete program as a snippet), which is much more convenient. Regards, Barend
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Barend Gehrels Sent: Thursday, March 24, 2011 7:07 PM To: boost@lists.boost.org Subject: Re: [boost] [documentation] doxygen tags and ALIASES.
Complete programs are the best basic examples. <snip>
The snippet avoids too much irrelevant 'housekeeping' that confuses the important part of the example.
That is true but... what is normally "irrelevant" or "trivial" for the author, can be a stumbling block for the user. Normally the only thing irrevant is "int main" and (sometimes) headerfiles. Occupying not too much space. All the rest, typedefs, namespace usings or aliases, are relevant housekeeping, which need to be present in examples.
Actually I don't see much examples or snippets in Boost doc's. And if there are, they are presented as an example but they are actually a test (e.g., using assert).
Well if you look a John Maddock's Boost.Math library, you will find extensive use of snippets. I find them excellent (but then I wrote some of them ;-) Steven's Boost.Units uses a lot of snippets. You are right that many examples In Boost docs are pretty unhelpful. No attempt to explain the important features of the example. Trouble is, people are getting tired by the time they get round to doing examples :-( The best of Boost.docs are really good - but there are plenty of poor to unsatisfactory libraries' docs.
Therefore, an example including a main (even if that is indeed trivial) and headerfiles is easy to copy and paste. And easy to maintain... And you can mix explanations between several snippets.
OK, this is possible with examples too. Especially the callouts are useful.
And the snippets are certain to be what has been compiled (can't get out of sync).
But you may need the full example to see all the details, and to try to run it (and perhaps modify it for your purposes).
Then you have it twice... And the example is then normally not syntax highlighted or annotaded, as in Graph. Graph has a lot of useful samples, by the way, but the presentation could just be better.
<aside> I've wondered why Mozilla Firefox (for example) when associated Textpad (my favourite which does syntax colouring) with .?pp files, does NOT do the syntax coloring when an example file is called up via Firefox. Has anyone got this to work? </aside>
ICL does a good job. Complete examples.
Doxygen has \example but I've not used that in anger yet. I think it includes the whole example file, and is mainly useful if you are looking at the standalone Doxygen format (which has some good aspects), but not so useful if using Quickbook etc.
In the previous version of Boost.Geometry doc's we used:
\dontinclude doxygen_1.cpp \skip example_envelope_polygon \line { \until }
to extract snippets (indeed). This required much care to extract just the right lines (especially in longer snippets).
Now we're using QuickBook example extracting (snippets indeed, but the complete program as a snippet), which is much more convenient.
Keep up the good work! Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of barend Sent: Wednesday, March 23, 2011 12:27 PM To: boost@lists.boost.org Subject: 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.
Correct, see http://www.stack.nl/~dimitri/doxygen/commands.html#cmdthrow also /example and /tparam http://www.stack.nl/~dimitri/doxygen/commands.html lists them all - lots!
Also notes and remarks are standard Doxygen.
So all this is quite easy. I've done it in as Doxygen comments in the C++ code - it's hard work! But done at the time of writing, it certainly does focus the mind. And it clutters the C++ part too, but I find that syntax coloring blots it out OK. (If you are using lots of MACROS and tricks, it gets messy). Paul PS Some use @ and others \ as the trip char. I'm a \ person ;-) --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
On 23-3-2011 18:06, Paul A. Bristow wrote:
Correct, see
http://www.stack.nl/~dimitri/doxygen/commands.html#cmdthrow
also /example and /tparam
http://www.stack.nl/~dimitri/doxygen/commands.html
lists them all - lots!
Also notes and remarks are standard Doxygen. So all this is quite easy.
Yep. The challenge is to get them all in the right way into QuickBook ;-)
I've done it in as Doxygen comments in the C++ code - it's hard work! But done at the time of writing, it certainly does focus the mind.
And it clutters the C++ part too, but I find that syntax coloring blots it out OK.
(If you are using lots of MACROS and tricks, it gets messy).
Paul
PS Some use @ and others \ as the trip char. I'm a \ person ;-)
I'm a \ person too ;-) /// is also possible but that clutters multi-line Doxygen comments a bit. Regards, Barend -- Barend Gehrels http://about.me/barendgehrels
AMDG On 03/23/2011 10:06 AM, Paul A. Bristow wrote:
PS Some use @ and others \ as the trip char. I'm a \ person ;-)
I actually use both ;). I use \ when it's something that becomes part of the output text, and @ for markup commands: \pre @c T must be \CopyConstructible In Christ, Steven Watanabe
participants (6)
-
barend -
Barend Gehrels
-
Paul A. Bristow -
Steven Watanabe -
Stirling Westrup -
Vicente BOTET