Geometry Boost List: Re: [geometry] specializing traits::tag for io operations and html code documentation

Subject: Re: [geometry] specializing traits::tag for io operations and html code documentation
From: Barend Gehrels (barend_at_[hidden])
Date: 2013-05-23 17:18:30

Hi Tomislav,

On 23-5-2013 13:21, Tomislav Maric wrote:
> Hi,
>
> I have a question about the tag dispatching engine. In the code I wrote
> for vtk, I defined vtk_writer tags and simple dispatching, but now I
> noticed in "tag.hpp" that each geometry needs to specialize traits::tag.

That is correct.

> Reading again wkt.hpp, I found in the wkt_manipulator:
>
>      template <typename Char, typename Traits>
>      inline friend std::basic_ostream<Char, Traits>& operator<<(
>              std::basic_ostream<Char, Traits>& os,
>              wkt_manipulator const& m)
>      {
>          dispatch::wkt
>              <
>                  typename tag<Geometry>::type,
>                  Geometry
>              >::apply(os, m.m_geometry);
>          os.flush();
>          return os;
>      }

That is right. I already noticed that your code did not follow exactly 
this model. Did not yet mail about it because your code seemed to work 
fine. But this code above is, in general how we do it (actually: how we 
did it, more about that later).  It is best described here:

http://www.boost.org/doc/libs/1_53_0/libs/geometry/doc/html/geometry/design.html

(there is also a pdf-paper about it: 
http://trac.osgeo.org/ggl/wiki/BoostCon , especially the 2010 paper). 
This design rationale describes how (and why) we use tag dispatching. 
Note we dispatch by type, not by instance (like you did). That gives 
also the possibility to use tag-dispatching in metafunctions (for example).

See also this blog-page, describing just the system:
http://barendgehrels.blogspot.nl/2010/10/tag-dispatching-by-type-tag-dispatching.html

Bruno enhanced the system by making the take a default template 
parameter. See for example the code in area.hpp, where it is like (extract):

template
<
     typename Geometry,
     typename Tag = typename tag<Geometry>::type
 >
struct area
{
// ...
};

This is not yet applied to WKT, but the difference is small and will be 
clear. Maybe area is a (slightly) better starting point then WKT.

> And above it, there are structs that specialize the apply function for
> different geometries. If I understood it right the geometries that are
> streamed in wkt are wrapped in wkt_*geometry* (e.g. wkt_box).

The last convention (wkt_box) is just the naming of helper functions, it 
can be anything (e.g. wkt_range, wkt_poly). But basically, yes, in 
namespace dispatch there is a structure specialized for all tags, 
implementing the functionality or forwarding to helper functions.

>
> I will need more time to wrap (pun intended :) ) my head around how
> formatting works if I want to make the vtk IO have the same design as
> the wkt.

Hope this mail and the doc helps.

> Is there a way I can generate Doxygen-like documentation of
> boost.geometry that shows all possible information about how the code is
> organized with cross-links? Searching through source helps, but having
> 20 tabs opened in a web browser might be more informative.

Yes there is. In boost/libs/geometry/doc/doxy there is a doxyfile. You 
can start doxygen exactly from there, and get output in doxygen_output.

We postprocess this to make quickbook documentation, so the focus is not 
on doxygen itself, but it is still working. But the details (dispatch 
and implementation details) are skipped, so I don't know if it is really 
useful for your current purpose...

Regards, Barend