-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: Tuesday, October 15, 2013 5:42 PM To: boost@lists.boost.org 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 +44 1539 561830 07714330204 pbristow@hetp.u-net.com