Geometry Boost List: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook

Subject: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook
From: Barend Gehrels (barend.gehrels)
Date: 2010-09-10 06:20:09

  hi Mateusz,

> I have some additional comments to the examples.
>
> In my opinion, the examples should state short and well-formed
> C++ programs, but not just snippets showing basically how to substitute
> argument names with values - it should be clear from reading
> documentation anyway

I see your point and now I understand your proposal for renaming 
snippets to examples better. Because I actually meant them as snippets.

Even if the example is complete (having int main(void) {} around it, and 
#include above it), it basically shows the same thing: substitute 
argument names. Often (especially showing strategies etc) it is not 
completely trivial. For example here: <http://bit.ly/cJXUW8> it shows 
why and how to use a strategy, more than substitution.

However, I agree with you, I like the cplusplus.com documentation and it 
has complete examples as well, it is useful to copy and paste. So we can 
use that approach. The most important for me is that these are really 
compiling examples, and I like it that QuickBook is able to extract them 
and display them with syntax coloring.

So yes, we can do it like that. The only problem I have with it is if 
there are many situations (intersection), there will be a long list of 
complete programs there, all having the same int main() etc.

> Second, the comments should be inlined in examples source code,
> but not just referred by numbers. It is easier and more
> convenient to track code&  explanation if presented in this form:
>
> // Set a coordinate. Note: prefer using bg::set<0>(point1,  1.0);
> point1.set<0>(1.0);
I really like that QuickBook functionality. It really makes the source 
code short, and can give some additional explanation. I think they can 
be used both, we can add comments where appropriate and notes where 
appropriate.

In the sample on area (link above), I think the QuickBook notes are more 
appropriate... If that had been comments, I would remove them. For 
hyperlinks it is probably always more convenient (besides that I'm not 
sure if QuickBook generates a hyperlink in normal C++ comments). And 
even in that set function, this is an annotation, explaining a better 
option, and not directly related to the program itself, which shows how 
to use that function...
So yes, I see your points and agree comments can be clear and should be 
used sometimes, but I think annotations are useful as well.

Regards, Barend