On Fri, Oct 25, 2013 at 6:10 PM, Mateusz Loskot <mateusz@loskot.net> 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 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