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

Subject: Re: [boost] [documentation] doxygen tags and ALIASES.
From: Barend Gehrels (barend_at_[hidden])
Date: 2011-03-24 15:07:00

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