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