Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-15 12:41:56
Mateusz Loskot wrote:
> Tools are crucial, but we haven't decided *what* those tools are
> supposed to do (extracting and hyperlinking bits of comments is not
> 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.
Here's the link to my own proposal for a "form filling" approach:
>> 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?
Here's my test case example:
> I'll follow Robert's suggestion: enable_if, Fusion, Iostreams, MPL,
I'm sure there are others - I haven't studied all of boost in detail.
> Why? The meta aspect of a library bumps the complexity of documenting it,
> so it's good to tackle meta-language-ish beasts first.
+1 - first decide what - then decide how - or better yet - let the person
who does decide how.
> 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 ) to
> document my
> library, it must be no-brainer boring form filling 
> 6 .I will pass the filled forms (doc source files) to the Boost
> Documentation repo to generate HTML pages at
> 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?
describes what has worked for me.
>  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
>  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.
The whole thrust of your email resonates with my feelings about the
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk