On 11 October 2013 13:42, Mathias Gaunard
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.
This is the one I'm referring to: https://svn.boost.org/svn/boost/trunk/libs/asio/doc/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...
IMHO, that is a useless kind of documentation. We've got IDEs and editors with decent code browsing capabilities for that.
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?)
I mean the second one.
generates some other layout with a symbol-centric approach rather than a header-centric one?
Yes. The basic idea is this: If I click a function name, I get details of that function. If I a function has more overaloads, I get extra intermediate page - listing of overloads. If I click a parameter, I get corresponding concept with its requirements. For example, 1) one of overloads http://www.boost.org/doc/libs/1_42_0/doc/html/boost_asio/reference/async_rea... 2) click on template parameter AsyncReadStream http://www.boost.org/doc/libs/1_42_0/doc/html/boost_asio/reference/AsyncRead... Such documentation is based on the natural process of reasoning about C++ Code.
The doxygen_xml2qbk tool in Geometry doesn't seem to be really like Asio's documentation.
As I mentioned, we've reached Asio-like prototype some time ago [1] , but due to XSLT complexity we've switched to simple generator, though it's not as capable as Asio's, yet. [1] (links broken, no longer online) http://lists.boost.org/Archives/boost/2010/02/161827.php
It's not header-centric but otherwise it looks pretty much like standard doxygen2boostbook docs. Maybe people prefer this?
Might be users prefer it, At least, that's what Geometry team prefers :-)
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.
I do as well, but I use code browsing tools for that.
In any case, I'd be interested to know more about the differences between doxygen2boostbook and xml2qbk to know which one I should use.
Barend described how it works for Geometry: http://barendgehrels.blogspot.co.uk/2010/12/doxygen-and-quickbook.html
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 find handwritten docs superior. The Doxygen comments make the code harder to browse, especially if programmers aspire to stick long essays with numerous code examples into them. IMHO, Doxygen comments should be very minimal and the bloat of documentation in separate Quickbook (or Markdown) files cross-referencing to symbols from code and Doxygen (separate plain text files with dosc make it easy to read without generating HTML/PDF, etc.) But, I guess we're getting into personal preferences There used to be a very long debate on boost-docs [1] about pros/cons of Doxygen and the outcome was within Boost, there are people who hate it and people who love it, hence best is to allow freedom of choice. [1] "Sphinx integration" thread :) http://lists.boost.org/boost-docs/2011/09/ http://lists.boost.org/boost-docs/2011/10 Best regards, -- Mateusz Loskot, http://mateusz.loskot.net