Boost logo

Geometry :

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.

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

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

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

> 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

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

Geometry list run by mateusz at