Re: The beauty of LATEX
Dave Abrahams <[email protected]>
| Newsgroups | gmane.comp.lib.boost.documentation |
|---|---|
| Message-ID | <[email protected]> |
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 > <[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. Yeah, try using it for functions built using Boost.Parameter, for example. Much is omitted. -- Dave Abrahams BoostPro Computing http://www.boostpro.com _______________________________________________ Boost-docs mailing list [email protected] http://lists.boost.org/mailman/listinfo.cgi/boost-docs