[Boost-docs] Content and function first (was: The beauty of LATEX)

Subject: [Boost-docs] Content and function first (was: The beauty of LATEX)
From: Mateusz Łoskot (mateusz_at_[hidden])
Date: 2011-10-17 17:30:59

On 17 October 2011 14:24, Paul A. Bristow <pbristow_at_[hidden]> wrote:
> I also suspect we are focussing too much on appearance. Â Function first!

+1 and discussing Sphinx I aimed function, not appearance, in case it
wasn't clear.
However, structure is closer to function than appearance, IMO.

> But beauty is also in the eye of the beholder - and I don't share the 'yetch' reaction of some to the current PDF appearance.
> We could (we have!) spent a lot of time fruitlessly opining about what is most beautiful.
>
>
> IMO it is *content* that is most important, which I why I am so keen on using a tool, for example Doxygen,
> for helping to automate the documentation of what classes and functions do, what parameters (and template
> parameters) do, what their pre and post-conditions are, when functions return, if and when they throw exceptions
> or return error code.

+1 but it is just a foundation.

I'd still insist to solve very simple exercise:

A tiny C++ library.
One concept.
One model.
One algorithm.

How do we want to document it using Doxygen (in combination with QuickBook)?
At low level, Doxygen documents the basic building blocks of and
syntactical entities of the library.
At high level, ...something needs to attach structure and semantic to
these blocks.

Doxygen solves issues at low-level of physical structure of content.
IMO, Doxygen needs to be complemented with:
1) glue framework provided by QuickBook (BoostBook)
2) glue content written by library authors
3) glue process.

> (Much of the opposition to use Doxygen is that some believe that you just chuck the source code into it, and it does everything.
> This is a complete delusion: Â the author must document what each function does, what parameter are etc. Â It's tedious work,
> but without that the output is just an outline of the overall C++ structure and lists of classes etc).

That's why I assumed the overall idea is a bit utopian.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org