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-04 05:00:34

  hi Luke,

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

Yes, it is possible. However it currently is a bit targeted (~5%) to 
Boost.Geometry; I've enough work on my list for the inclusion of 
Boost.Geometry, so will not explicitly working on it. But I thought (and 
think) of it too when coding it. It is currently work in progress and 
too early to submit it anyhow.

> About the documentation in general, is there a way to use Doxygen 
> comments to link to an image?

Yes, it is, and it currently is included, should have added a deeplink 
as well. Here it is.
<http://bit.ly/dvJzzf>

This is the Doxygen way, so no special things here.

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

Yes, there  is a relation, but:
polygon + polygon can give an intersection in the form of a 
(multi)polygon, implemented
polygon + polygon can give an intersection in the form of a point set 
(multipoint), this is not ready but the basics are there and will be 
implemented
polygon + polygon can give an intersection in the form of a linestring 
(shared boundaries), this is not implemented and will not be in the 
first version
etc

But some other things does not make sense:
point + point can give a point
point + point can never give a useful linestring or a polygon, so this 
combination will not compile
etc

Or it might even be useful that the last combination also compiles (if 
people use it in a very abstract way) but than it will give empty 
output, or output with one point, or an exception. That is to be decided 
later.

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

Agree and that is indeed the idea. QuickBook supports pictures within 
tables.

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

Also agreed, we have a combinatorial amount of effort required here.

> Good work, by the way.

Thanks, Barend

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/ggl/attachments/20100904/dfd26665/attachment-0001.html