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

Subject: Re: [geometry] Register CCW Polygon
From: Andrew Hundt (athundt_at_[hidden])
Date: 2013-10-25 23:31:26

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.

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.

> 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<http://www.boost.org/doc/libs/1_54_0/libs/geometry/doc/html/geometry/examples.html>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"
   - Explain that each of these definitions is a specialization of existing
   utilities in Boost.Geometry
   - Each specialization "explains" to Boost.Geometry with the way to use
   each type
   - A specialization must be provided for each possible interaction type

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.

> Regarding the tag dispatching, Barend Gehrels gives a very good overview
> of those C++ techniques on his blog:
>
> http://barendgehrels.blogspot.co.uk/search/label/tag%20dispatching

I've actually personally commented here before on how good that article is.
:-)

Cheers!
Andrew Hundt