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

Subject: Re: [Boost-docs] Content and function first (was: The beauty of LATEX)
From: Joel de Guzman (joel_at_[hidden])
Date: 2011-10-17 22:30:59

On 10/18/2011 1:30 AM, Mateusz Łoskot wrote:
> 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).

To many of us, Doxygen is simply out of the question. A C++ library is
not just a bunch of Java-ish functions and member functions API that
Doxygen is designed for.

So, you hijacked this thread regardless of my plea not to:
"Please, I don't need another "just use XXX or YYY instead of
Quickbook" answer". It's not relevant to my question. Don't
you think I value function before form? But ***THAT*** is
not the my question. Ah, yeah, you created a new thread.

Regards,
-- 
Joel de Guzman
http://www.boostpro.com
http://boost-spirit.com