Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2013-10-15 10:32:35

On 15 October 2013 09:33, Paul A. Bristow <pbristow_at_[hidden]> wrote:
>> Mateusz Loskot wrote:
>> On 14 October 2013 18:39, Paul A. Bristow <pbristow_at_[hidden]> 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/vector.html
>>
>> 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