On 11/10/13 12:12, Mateusz Loskot wrote:
Yes, it does, but apparently it does not produce the quality Boost.Asio aimed for.
The reference.xsl sheet produces clear index:
http://www.boost.org/doc/libs/1_54_0/doc/html/boost_asio/reference.html
and neatly gathers overloads and specialisations in clickable way leading to documentation of particular version of an entity:
http://www.boost.org/doc/libs/1_54_0/doc/html/boost_asio/reference/read.html
I don't really know reference.xsl. The default Doxygen postprocessing ($BOOST_ROOT/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl) gives a list of header files with for each of them the symbols in them. Something like the Boost.Container docs that were referenced earlier in this thread: http://www.boost.org/doc/libs/1_54_0/doc/html/boost_container_header_referen... So you say that reference.xsl (there are two of those, one in tools/boostbook/xsl, one in libs/asio/doc, which one do you mean?) generates some other layout with a symbol-centric approach rather than a header-centric one? The doxygen_xml2qbk tool in Geometry doesn't seem to be really like Asio's documentation. It's not header-centric but otherwise it looks pretty much like standard doxygen2boostbook docs. Maybe people prefer this? I personally quite like the header-centric approach, but that may be because I'm just used to thinking in terms of header files first as the structure of a library. In any case, I'd be interested to know more about the differences between doxygen2boostbook and xml2qbk to know which one I should use.
The typical Boost way is to drop in everything into single Synopsis section, like here:
http://www.boost.org/doc/libs/1_54_0/libs/spirit/doc/html/spirit/qi/referenc...
I wouldn't call any of the Spirit docs "typical Boost way". This stuff is entirely handwritten as far as I know. I personally find that the Spirit docs have some problems, because the documentation is not always in sync with real code and because the headers symbols were declared or defined in can be hard to find.