Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Mateusz Łoskot (mateusz_at_[hidden])
Date: 2011-10-18 10:48:17

On 18 October 2011 11:40, Matias Capeletto <matias.capeletto_at_[hidden]> 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...

Boost.Asio approach could solve this quite neatly [1].
- async_write.html is where "as only one" documentation goes
- "read more" is where specialisation-specific documentation goes

[1]
http://www.boost.org/doc/libs/1_47_0/doc/html/boost_asio/reference/async_write.html

> For now, I think one possible
> solution is to give people a good set of Quickbook templates to help
> them write the reference section of their docs. They can even put this
> qbk parts inside the actual source files as Rene is proposing.

QuickBook templates is a great idea.

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