[geometry] Documentation prototype for review
Hi, I'm working on documentation of Boost Geometry based on Quickbook and I've prepared a prototype: http://mateusz.loskot.net/tmp/ggl/qbk/ What I'm doing is manually porting the content from Doxygen-based (http://geometrylibrary.geodan.nl/) plus restructuring, reformatting and completing it with missing details. I'd like to ask everyone who is interested in Boost Geometry library for comments, impressions and suggestions of improvements. Note, nodes marked with (?) are not finished and empty, but included to give impression about the overall structure. I'd be especially interested comments about the structure, if it's accessible to new users and usable for advanced users at the same time. The Reference is one of the most important section I'd like to master, so please share your comments on the form and completeness of the concepts specification, for example: http://mateusz.loskot.net/tmp/ggl/qbk/geometry/reference/geometries/concepts... types description, for example: http://mateusz.loskot.net/tmp/ggl/qbk/geometry/reference/geometries/types/po... and functions description: http://mateusz.loskot.net/tmp/ggl/qbk/geometry/reference/arithmetic/add_poin... Thanks in advance for your feedback. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Mateusz Loskot Sent: Sunday, February 14, 2010 12:38 AM To: boost@lists.boost.org Subject: [boost] [geometry] Documentation prototype for review
I'm working on documentation of Boost Geometry based on Quickbook and I've prepared a prototype:
http://mateusz.loskot.net/tmp/ggl/qbk/
What I'm doing is manually porting the content from Doxygen-based (http://geometrylibrary.geodan.nl/) plus restructuring, reformatting and completing it with missing details.
I'd like to ask everyone who is interested in Boost Geometry library for comments, impressions and suggestions of improvements.
The Reference is one of the most important section I'd like to master, so please share your comments on the form and completeness of the concepts specification, for example:
This is looking nice - but so was the Doxygen based version. I believe (and found 'eating my own dogfood' -especially the SG plot project) that the Doxygen produced Reference section is complementary to the more textual sections that you are writing. Several libraries use both, see Boost.Units, Accumulator, (and of course the NotAlibrary SVGPlot Soc 2007/vizisualization) and I think this is much the best way to go, especially as you have already done the tedious task of adding Doxygen style comments to the code, so that you (and readers) would lose much if you don't provide it. A drawback is that docs generation time goes up sharply, so you may prefer to leave it to the end. I found it was wise also to generate Doxygen only version first to check you don't have any warnings - its quicker that way. And users will also find it useful to just have the full doxygen version too - it is also complementary. Finally I would say that I found the Quickbook embedded code system very, very useful. This ensures that the examples cannot get out of sync with the code. and I found numbering sections algorithms_append_hpp_1, algorithms_append_hpp_2 ... and also using algorithms_append_hpp_output to show some or all of the output. I put the output in a C comment like this /* //[auto_1d_plot_output auto_1d_plot.cpp Linking... Embedding manifest... Autorun "j:\Cpp\SVG\debug\auto_1d_plot.exe" limit value: 1.#INF 6 good values, 1 limit values. limit value: 1.#INF x_range() 0, 7 //] [auto_1d_plot_output] */ which can be referenced by the QuickBook text. You will find that trying to produce the pdf is also useful to iron out any residual bugs - as well as producing a text searchable version that will help users. Good luck! Paul --- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
Paul A. Bristow wrote:
Mateusz Loskot wrote: I'm working on documentation of Boost Geometry based on Quickbook and I've prepared a prototype:
http://mateusz.loskot.net/tmp/ggl/qbk/
What I'm doing is manually porting the content from Doxygen-based (http://geometrylibrary.geodan.nl/) plus restructuring, reformatting and completing it with missing details.
I'd like to ask everyone who is interested in Boost Geometry library for comments, impressions and suggestions of improvements.
The Reference is one of the most important section I'd like to master, so please share your comments on the form and completeness of the concepts specification, for example:
This is looking nice - but so was the Doxygen based version.
The problem with Doxygen version is that it lacks of important details. So, by the way of updating the documentation, we've decided to move to Quickbook format. AFAIU, it is a preferred format for Boost docs.
I believe (and found 'eating my own dogfood' -especially the SG plot project) that the Doxygen produced Reference section is complementary to the more textual sections that you are writing.
Yes, that's right. I agree Quickbook work means more or less manual rework of what Doxygen generates.
Several libraries use both, see Boost.Units, Accumulator, (and of course the NotAlibrary SVGPlot Soc 2007/vizisualization)
I have checked Acccumulator docs and I have to admit its reference is nothing more to me than a headers/code browser. It includes very little information. The Units does it better and I've just learned that pages like this http://www.boost.org/doc/libs/1_42_0/doc/html/boost/units/unit.html is generated from Doxygen comments...hmmm
and I think this is much the best way to go, especially as you have already done the tedious task of adding Doxygen style comments to the code, so that you (and readers) would lose much if you don't provide it.
Yes, now I can see the point and that it's possible to combine both, Quickbook and Doxygen. Sounds as the best option indeed.
I found it was wise also to generate Doxygen only version first to check you don't have any warnings - its quicker that way.
Doxygen lint-like functionality is helpful, indeed.
Finally I would say that I found the Quickbook embedded code system very, very useful. This ensures that the examples cannot get out of sync with the code. and I found numbering sections algorithms_append_hpp_1, algorithms_append_hpp_2 ... and also using algorithms_append_hpp_output to show some or all of the output.
I put the output in a C comment like this [...] which can be referenced by the QuickBook text.
Right, sounds like a very useful feature. Paul, thank you for your suggestions. It opens new approach that seems much better than hand-only crafted docs. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org
AMDG Mateusz Loskot wrote:
I have checked Acccumulator docs and I have to admit its reference is nothing more to me than a headers/code browser. It includes very little information.
The Units does it better and I've just learned that pages like this http://www.boost.org/doc/libs/1_42_0/doc/html/boost/units/unit.html is generated from Doxygen comments...hmmm
Yow. I missed those BOOST_MPL_ASSERTS. In Christ, Steven Watanabe
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Mateusz Loskot Sent: Saturday, February 20, 2010 2:53 PM To: boost@lists.boost.org Subject: Re: [boost] [geometry] Documentation prototype for review
Several libraries use both, see Boost.Units, Accumulator, (and of course the NotAlibrary SVGPlot Soc 2007/vizisualization)
I have checked Acccumulator docs and I have to admit its reference is nothing more to me than a headers/code browser. It includes very little information.
The Units does it better and I've just learned that pages like this http://www.boost.org/doc/libs/1_42_0/doc/html/boost/units/unit.html is generated from Doxygen comments...hmmm
Sadly the work of devising the units library was so great that the authors lacked the strength to go through and Doxygen comments all the code - a massive, boring but useful, task, but one that might still be an 'exercise for the student' - perhaps a GSoC project.
and I think this is much the best way to go, especially as you have already done the tedious task of adding Doxygen style comments to the code, so that you (and readers) would lose much if you don't provide it.
Yes, now I can see the point and that it's possible to combine both, Quickbook and Doxygen. Sounds as the best option indeed.
You can get more of the flavour of what can be achieved by glancing at the SVG plot docs. Here all (I hope) of the functions etc are Doxygen commented. Doxygenating the C++ code was a *lot* of work, but the end result is very user helpful IMO, and you can be much more confident that it follows source code changes. You've already done most of the hard work... Paul --- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
participants (3)
-
Mateusz Loskot -
Paul A. Bristow -
Steven Watanabe