Re: [boost] Improving Documentation

On 15 October 2013 09:33, Paul A. Bristow wrote:

...

Mateusz Loskot wrote: On 14 October 2013 18:39, Paul A. Bristow wrote:

...

Mathias Gaunard wrote:

...

On 12/10/13 19:59, Eric Niebler wrote:

...

I've also been frustrated by the poor support for concepts in our documentation toolchain. "Just write your docs in Boostbook XML" is like telling people to program in assembly -- if assembly were extremely verbose.

Maybe Quickbook could be extended to be able to output the required XML for concepts?

What is required that is not already provided by Doxygen comments of type

\tparam \param \pre \post \returns etc?

If we have a concept like

template <class T> struct DefaultConstructable;

It will be possible to get a link to this from \tparam description

\tparam The type of the elements stored in the circular_buffer. T has to be DefaultConstructible.

---

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This sentence should not even appear there, but something like:

\tparam The type of the elements stored in the circular_buffer. \modelof DefaultConstructible

and that's important point of the whole debate, IMHO.

OK - modelof would be nice but:

1 We could get \modelof added to Doxygen.

Yes, that is a good idea.

2 The key information DefaultConstructible is present - a big improvement on the current situation. And if you go to the source hpp, you will also find the comment with this info.

It is present, but without important context and semantic. The lack of context and semantic in "raw docs" is what makes it hard to generate clear, consistent and friendly end-user documentation. All the gymnastics like Boost.Asio's XSLT, Boost.Geometry's doxygen_xml2qbk, etc. have been invented to apply the missing context and semantic to bits and pieces extracted by Doxygen.

...

It is about marking, extracting, formatting, synthesizing and interlinking all of the animals in the C++ vocabulary:

I have a long term vision of starting with Clang and adding the documenting-from-comments features, but we are way off that. A GSoC project?

The clang utilisation is what I have been thinking of myself, since I discovered http://jessevdk.github.io/cldoc/

We also perhaps don't want to put a lot of work into making BOOST_CONCEPTS work automatically, only to find that it obsolete if concepts are added to C++.

For a year or several, we should be using the tools we have to best.

Tools are crucial, but we haven't decided *what* those tools are supposed to do (extracting and hyperlinking bits of comments is not enough). Let's *forget* about the tools and focus on creating the "form filling" framework, creating the Boost documentation structure with gaps to be filled with content.

From the docs quality perspective, it does not really matter how we fill those gaps, manually or with the tools. Certainly, from productivity and such perspective, tools are crucial, but we still haven't decided what those tools would do :)

IMHO, we try to solve micro-problems of markup and tools too early, whereas we should rather stick to top-bottom approach.

...

If I have a concept EasilyDocumentable, how shall I stuff Doxygen with data to get page like this?

http://www.boost.org/doc/libs/1_54_0/libs/utility/CopyConstructible.html

If you wish I could tackle this now - but I'm too busy with a bout of industrial strength DIY at present ;-)

"how shall I stuff Doxygen"? Teach me please, I can wait :-)

But when I'm free, is this worth tackling?

I linked the "good examples" docs assuming those are exemplars we should try to aim, so where the doubt/question comes from?

...

If I have a model well_documented, how...like this?

http://www.boost.org/doc/libs/1_54_0/libs/fusion/doc/html/fusion/container/v...

...

with "model of" list of corresponding concepts, valid expressions and semantics would be nice too.

It's OK - but it's very much reference info - it doesn't have hyperlinks to explain much - not even links to the source files!

I can't get the importance of links to source files. That is secondary, if not a more remote, issue in the Boost docs project, IMHO.

As an test example, it's also a bit of a googly because Fusion a bit of a weird and wonderful meta-language-ish beast.

Another test-case example?

I'll follow Robert's suggestion: enable_if, Fusion, Iostreams, MPL, Spirit. Why? The meta aspect of a library bumps the complexity of documenting it, so it's good to tackle meta-language-ish beasts first. To summary, let me repeat what is *my* problem with documenting Boost, what I have been grinding in this thread in almost every post: 1. I have created my first library Boost.XYZ. 2. I haven't put a single line of C++ comment in Boost.XYZ sources. 3. I have collected all the tiniest details about every template, class, function, concept, pre-/post-condition, ... in my head. 4. I need forms or templates that I can fill with *all* those details I have collected about Boost.XYZ? 5. I will be filling those forms manually, in my favourite text editor. NOTE: I don't want to learn new language (yet [1]) to document my library, it must be no-brainer boring form filling [2] 6 .I will pass the filled forms (doc source files) to the Boost Documentation repo to generate HTML pages at http://www.boost.org/libs/xyz/ where *all* those details will be presented in canonical way (SGI STL, Robert's examples), using consistent formatting and typography, properly interlinked (concepts, refinements, models,...), <all the fancy output features here> 7. Where can I find the forms? [1] Learning new language or tool shall be necessary *only* if I want to use it, but may like manual labor of writing from top of my head [2] Implies easy automation with tools Are the expectations outlined above invalid and I'm misunderstanding the whole problem? If yes, then I'll rewind, go back and seek to learn the right way. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net