[boost] GGL documentation issue

Subject: [boost] GGL documentation issue
From: Thomas Klimpel (Thomas.Klimpel_at_[hidden])
Date: 2009-11-17 19:48:34

Dear GGL authors,

This is still not a review. However, the documentation issue I found doesn't allow be to submit a (positive) review before the issue is clarified.

> - What is your evaluation of the documentation?

Looks like "work in progress" to me. There are examples, but examples are not a sufficient substitute for a proper documentation.

But I wonder whether it's just me, or whether the documentation is really insufficient. I know the library has a "ring concept", so let's try to find out from the documentation what it is.

On "Related Pages" -> "OGC (Open Geospatial Consortium)" the following definition can be found:
linear_ring: Sequence of point values with linear interpolation between points, which is closed and not self-intersecting

On "Modules" -> "geometry concepts: defines and checks concepts for geometries" -> "ring concept More..." the following can be found:

template<typename Geometry>
class ggl::concept::Ring< Geometry >
ring concept

Formal definition:
    The ring concept is defined as following:

        * there must be a specialization of traits::tag defining ring_tag as type
        * it must behave like a Boost.Range
        * there can optionally be a specialization of traits::point_order defining the order or orientation of its points, clockwise or counterclockwise.
        * either it can behave like the std library, having pushback
        * or it can implement a mechanism for clearing and adding points. This is the same as the for the concept Linestring, and described there.

Note:
    to fulfil the concepts, no traits class has to be specialized to define the point type. The point type is taken using boost::range_value<X>::type 

Both explanations don't seem to clarify what a ring really, so let's continue to browse the documentation. On "Modules" -> "A Generic Geometry Library (web-copy of article for BoostCon'09)", it is described how a triangle can be handled as a linear ring. This is indeed illuminating, because I learn from it that a "ring" is indeed a geometric figure with a non-zero area, and that there is no requirement for the first and last point of the ring to be equal. And "Example" -> "c04_b_custom_triangle_example.cpp" also contains the example from the article, so I went and tried it. It seemed to work well, but then I tried what happens when I comment out the area specialization. Suddenly the area was zero???

And I'm really confused now: What I initially wanted to find out was whether a ring is a geometric figure with a non-zero area. Now I'm wondering whether there is a requirement for the first and last point of a ring to be equal. A look at "Example" -> "c04_a_custom_triangle_example.cpp" indicates that this might indeed be the case:
struct triangle : public boost::array<ggl::point_xy<double>, 4>

My conclusion is that the documentation of the "geometry concepts" is insufficient, because I'm not even able now to tell whether there is a bug in the library or a bug in the example. And that the examples that are provided instead of a proper documentation contradict each other doesn't help either.

Please clarify:
a) Do you agree that the documentation of the "geometry concepts" is currently insufficient, because both the intended semantic meaning and the exact constraints on valid "values" for objects modeling the "geometric concepts" are not documented?
b) Why are there two examples that more or less contradict each other?
c) Is there a bug in the area function, or are both "Modules" -> "A Generic Geometry Library (web-copy of article for BoostCon'09)" and "Example" -> "c04_b_custom_triangle_example.cpp" wrong?

Regards,
Thomas