Re: The beauty of LATEX
Mateusz Łoskot <[email protected]>
| Newsgroups | gmane.comp.lib.boost.documentation |
|---|---|
| Message-ID | <CABUeae_9VwmxWr-dpbQOc4t2wQ1vx7Qtt==jpGKenz=6Tacsgg@mail.gmail.com> |
On 18 October 2011 11:40, Matias Capeletto <[email protected]> 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... 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 _______________________________________________ Boost-docs mailing list [email protected] http://lists.boost.org/mailman/listinfo.cgi/boost-docs