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-25 05:57:29

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]]
> On Behalf Of Barend Gehrels
> Sent: Thursday, March 24, 2011 7:07 PM
> To: boost_at_[hidden]
> 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
[phone]  07714330204
pbristow_at_[hidden]