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