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 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.
+1 Here's the link to my own proposal for a "form filling" approach: http://rrsd.com/blincubator.com/requirements_documentation/
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: http://htmlpreview.github.io/?https://raw.github.com/robertramey/safe_numeri...
I'll follow Robert's suggestion: enable_if, Fusion, Iostreams, MPL, Spirit.
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 [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?
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? 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 subject. Robert Ramey