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

Subject: Re: [boost] [documentation] doxygen tags and ALIASES.
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-03-24 12:59:52

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]]
> On Behalf Of Steven Watanabe
> Sent: Wednesday, March 23, 2011 6:48 PM
> To: boost_at_[hidden]
> 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:
> >
> > 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.

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
[phone]  07714330204
pbristow_at_[hidden]