Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-10-16 05:27:45

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Robert Ramey
> Sent: Tuesday, October 15, 2013 5:42 PM
> To: boost_at_[hidden]
> Subject: Re: [boost] Improving Documentation

<snips>

> > 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.

Stop right there! - it isn't going to be 'Boost Quality'.

Even if it is function-perfect, it isn't maintainable. 

The lifetime of most Boost code is longer than the 'lifetime' of the author - before being MIA.  

> > 3. I have collected all the tiniest details about every template,
> > class, function, concept, pre-/post-condition, ... in my head.

Mistake?  (Or is it that I can't remember what I had for breakfast?)

> > 4. I need forms or templates that I can fill with *all* those details
> > I have collected about Boost.XYZ?

You should have put that info with the code as you were writing!

The 'form or template' *IS* the code.  You will fill in

\brief  description
\details (you might reference concepts here? - for now)
\tparam
\param
\pre
\post
\returns
\throws

at least, for functions, and where appropriate classes, macros, data items...

> > 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]

Writing the "what this library does for you", "tutorial on how to use it" etc *can't* be a form
filling exercise. 

Quickbook is a good tool (using your favourite text editor - Quickbook syntax coloring is even nicer
but not essential), but you can use others.

> > 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?
> 
> http://rrsd.com/blincubator.com/tools_documentation/
> 
> describes what has worked for me.
> 
> > [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?

No - I think your expectations are reasonable - but over optimistic about what can be automated.

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]