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


> 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,
Charter Member of OSGeo,
Member of ACCU,

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC