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: Simonson, Lucanus J (lucanus.j.simonson)
Date: 2010-09-03 12:17:26

Barend,

It sounds like Doxygen to QuickBook is/has been a lot of work.  If you have created a methodology and tool (doxygen_xml2qbk) that can help others with the same task I think pretty much every new boost library could potentially benefit.  Have you considered contributing your work to boost by enhancing their boostbook related web pages to help others who face the same problems you have solved?

About the documentation in general, is there a way to use Doxygen comments to link to an image?  What the documentation is really missing is pictures to explain what the text is describing.  (Yes, I know only too well that my own documentation is lacking pictures as well, we are the pot and the kettle, here.)  If each algorithm gets its own page it makes more sense to have a picture on that page.  Is there a way to use Doxygen to create a link to an image?  Post processing the doxygen is probably not an optimal solution.

About the intersection algorithm documentation in specific (your deep link) it doesn't make sense to me that the output data structure limits the return type, the output concept type should be required by the combination of input concept types.  If you pass linestring as the output for linestring inputs, for example, do you get points out also as degenerate linestrings, or do you also have to call it with points as the output to get the intersection points?  Does your implementation currently support passing in two polygons and a list of linestring as the output and getting shared boundaries?  I find the documentation for intersection still somewhat confusing.  Perhaps if you documented each example of inputs and output type combination supported (with a picture for each) it would be very clear.  Also, since completeness (all geometry type pairs at input and all output types combinations supported) is probably not realistically attainable for all algorithms it makes sense to document which combinations are s
upported.

Good work, by the way.  Doxygen to quickbook makes a more polished and professional looking web page than what I hacked together manually with frontpage.  You have a diversity of fonts, font sizes, bold and italics that really distinguishes what each type of text is for and makes the page very readable.

Regards,
Luke

________________________________
From: ggl-bounces_at_[hidden] [mailto:ggl-bounces_at_[hidden]] On Behalf Of Barend Gehrels
Sent: Friday, September 03, 2010 3:40 AM
To: Generic Geometry Library Discussion
Subject: Re: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook

hi all,

Mateusz Loskot wrote:
Yesterday I managed to get first good results of processing Doxygen
XML output to Quickbook/Boostbook documentation.

(...)
Generally speaking, I've reviewed docs of most of Boost C++ Libraries and
I decided that Boost.Asio is the best example to follow. Boost.Asio is a
complex library,
it heavily uses Doxygen comments and, IMHO, it integrates them with
Quickbook/Boostbook

Last month I have worked on Boost.Geometry documentation using the Doxygen/QuickBook approach which Mateusz started this year.

The new version can be here: <http://bit.ly/aeFqXP><http://bit.ly/aeFqXP>

A few notes:
- the reference Mateusz created is currently a bit stripped, this is for development, to not be overwhelmed by 100ths functions to be filled in, and also convenient for review to not see 100ths of functions which are not yet documented. But the larger version will come back, of course
- even then not all which is listed there is (completely) documented. I will give some deep links below of things representable
- the reference pages can be quite documented, (possibly) having code snippets, behavior, complexity, images,
- I found the xsl procedure quite hard, and not yet complete. After pondering a while I decided that C++ is my tool. So I left the xsl approach for interpretation of Doxygen, and am using now a relatively simple C++ tool using RapidXML. This works great and can be easily customized up to the level we want. Of course xsl is still there because part of the QuickBook->BoostBook->DocBook->html conversion process, and also the reference section is still in XML as there is AFAIK no quickbook counter part
- the generated documentation is still Doxygen/Quickbook compatible (be it that for snippets and some other things this is not possible) but I don't know if it is necessary to keep this
- I'm currently working in the subfolder "qbk" and left the quickbook folder as it was, copying necessary files from there
- not all pages from the original "human written docfiles" are already there, some (also some already processed) will be added later
- most things are committed, such that you can see documentation source tags; I will review my changes on intersection and this will be committed today or tomorrow

Some deep links:
<http://bit.ly/aT6dbW><http://bit.ly/aT6dbW> for documentation on area
<http://bit.ly/boi5PX><http://bit.ly/boi5PX> for documentation on intersection, also based on Hartmut's questions last week
<http://bit.ly/a2f5dZ><http://bit.ly/a2f5dZ> for documentation on the geometry::point class
<http://bit.ly/b3rBlu><http://bit.ly/b3rBlu> for documentation on the BOOST_GEOMETRY_REGISTER_POINT_2D macro

Please let me know what you find.

The doxygen interpretation tool (doxygen_xml2qbk) is currently in <http://bit.ly/an158r><http://bit.ly/an158r>

Finally, I'm traveling coming month, most of the time, so there will be periods that I'm not reading my mail.

Regards, Barend

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/ggl/attachments/20100903/5abbadbe/attachment.html