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: Mateusz Loskot (mateusz)
Date: 2010-09-10 17:42:54

On 10/09/10 11:20, Barend Gehrels wrote:
>> 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.

Hi Barend,

Yes, that's my point basically.

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

It is, indeed.

The difference is only in intention: make user's life easier as much as
possible. I know, it may sound strange or ridiculous, but...
not being able to quote Karl Vogel precisely, if a user is not given
what he is looking for within 1 minute, he is likely going to leave the
page, forget Boost.Geometry and try to find another project with
easier (quicker) documentation :-)

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

Yes, good example.

> However, I agree with you,

I appreciate.

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

Yes indeed, it is a good idea to make full use of this capabilities.

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

Another approach is to have examples not inlined in documentation pages,
but linked. I think some libraries link files with complete examples as
.cpp files translated to HTML pages (AFAIU Boost.Spirit does it).

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

My point is to not force reader to jump from source to explanation.

> In the sample on area (link above), I think the QuickBook notes are
> more appropriate... If that had been comments, I would remove them.

Why to remove comments?
Do you mean technical limitations in Quickbook?

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

Can we make the numeric references next to source code as clickable
links leading to explanations and references next to exaplantaion
links jumping back to source code?

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

Good. I think it's important to figure out those details
and make the docs properly presented.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org