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