Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Dave Abrahams (dave_at_[hidden])
Date: 2011-10-19 01:09:03

on Tue Oct 18 2011, Matias Capeletto <matias.capeletto-AT-gmail.com> wrote:

> On Tue, Oct 18, 2011 at 11:35 AM, Paul A. Bristow
> <pbristow_at_[hidden]> wrote:
>> But surely documenting the classes, member functions and functions
>
>> API is *part* of the task we are
>> discussing?
>>
>> So I really, really do want to see *a* way of helping authors to
>> provide that information. Â The
>> Doxygen C++ code comments  /pre /post /param /tparam /returns
>> provide it : Â "source coupled
>> documentation" as Rene Rivera dubs it.
>>
>> I'm adamant that this requires a tool that 'understands' C++
>> Â (Gcc/Clang?) : that's all that many
>> libraries are using Doxygen for.
>
> The problem is that when you try to document generic C++ libraries, it
> is really difficult to obtain the right information to make a useful
> reference for the user with automated tools. For example, you can get
> several free functions that are just there to gain performance (think
> of sort) and should be documented as only one...  the concepts are the
> important bit here, and we still do not have them as part of the
> language. Or you can have big templates machinery with ton of classes
> that serves as the guts of the lib. In a lot of modern C++ libs, much
> of the code, classes, functions, are implementation details and the
> real public API is quite buried and not easily obtained by the use of
> Doxygen like tools. 

Yeah, try using it for functions built using Boost.Parameter, for
example.  Much is omitted.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com