Boost logo

Geometry :

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:

(there is also a pdf-paper about it: , 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:

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):

     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

Geometry list run by mateusz at