Geometry Boost List: Re: [geometry] Register CCW Polygon

Subject: Re: [geometry] Register CCW Polygon
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2013-10-30 19:49:05

On 26 October 2013 04:31, Andrew Hundt <athundt_at_[hidden]> wrote:
> On Fri, Oct 25, 2013 at 6:10 PM, Mateusz Loskot <mateusz_at_[hidden]> wrote:
>>
>> I'm afraid, that get up and run quickly in case of C++ library heavily
>> based on metaprogramming requires quite a bit of knowledge
>> of idioms far beyond the C++ OOP.
>
>
> I believe there may be a sufficient number of people in between
> "intermediate C++ developer" and "metaprogramming library author" that are
> fully capable of using the functionality demonstrated on the quick start
> guide but may have no idea that tag dispatching exists, much less how to use it.

You may be right, but at the same time to make everyone content is
very difficult.

> I also think it may be reasonable for such a person to want to make
> Boost.Geometry work with their own user defined type when the macros don't
> work, since it only requires a very basic understanding of what is going on.
> I think that with a little additional guidance it would be easier to create
> the specialization and get it to work with their types.

IMHO, the "Example: Adapting a legacy geometry object model" section is very
well written. Certainly, reading the source code of the examples is a
must as well.
If you have a concrete place or example of what's missing, please patch it.

>> > Therefore, I feel like a bit of
>> > explanation of what is being done and why in the documentation of the
>> > examples would make them a lot more helpful.
>> >
>> > Does that make sense?
>>
>> Yes, it does, but I personally think Boost.Geometry documentation is not
>> the
>> right place to explain general C++ techniques and idioms. It tries to
>> mention
>> names of well-known techniques and users are supposed to seek help
>> on C++ discussion groups, books, etc.
>>
>> However, if you think there are BG specifics missing in the docs,
>> please point it out and suggest what needs to be clarified.
>> Certainly, there is lots of room for improvements in the documentation.
>
>
> I think adding a few things in slightly more detail to the geometry
> adaptation examples may help people to integrate without fully
> comprehending, but still avoid writing a fundamentals book in the boost
> docs.
>
> Perhaps something like the following, but with a little more detail and
> accuracy, could help?
>
> Inline the code and the registration examples explanation like in the "quick
> start"

Sure, perhaps that would help, although I personally don't like
lengthy inline comments. A short and clean C++ code works best IMO.

> Explain that each of these definitions is a specialization of existing
> utilities in Boost.Geometry

It is very clear from the code, isn't it?

namespace boost
{
    namespace geometry
    {
        namespace traits
        {
            template<>
            struct tag<QLineString>
            {
                typedef linestring_tag type;
            };
        }
    }
}

where

boost::geometry::traits::tag is specialised for QLineString.

> Each specialization "explains" to Boost.Geometry with the way to use each
> type

it says so, by 1) stating "specialisation of traits" 2) using C++ syntax,
so everyone who reads code like this can clearly see what it is:

    template<>
    struct tag<QLineString>
    {
        typedef linestring_tag type;
    };

> A specialization must be provided for each possible interaction type

IMHO, it is presented in the code blocks, implicitly though:

For "Adaption of QPoint", one can see exactly what needs to be specialised,
many things. Whereas in "Adaption of QLineString", there is just one
specialisation. I guess, conclusions for a reader should be fairly clear.

> I'm just thinking back to my own experience from a couple years ago of
> learning how to integrate, and my additional experiences afterwards
> explaining what was going on to my coworkers.

I do understand your point and I agree with it, there is room for improvements.
At the same time, perception if a documentation is good/bad, complete/incomplete
is subjective as a process of learning is.

I'd suggest that if anyone things something is missing or unclear, then
please top the gaps up, write what's missing, reword or correct what's unclear,
svn diff and submit a patch for review.

If something is not written as well as one expects, there are two
obvious possibilities:
1) nobody was able to express it better than it has been written
2) manpower shortage.

Best regards,
-- 
Mateusz  Loskot, http://mateusz.loskot.net