Re: The beauty of LATEX

On Tue, Oct 18, 2011 at 11:35 AM, Paul A. Bristow
<[email protected]> 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. When I tried to use it for Bimap, the resulting
documentation was only useful as a navigation aid for someone that
wants to know how the lib is implemented. And that was after a lot of
manual work, making some parts of the codes invisible to it using
macros, and adding \code comments to directly replace some parts to
help it. Maybe in the future, our language, augmented with real
concepts will be more treatable. 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.

Best regards
Matias