On 20/07/07, Andrew Sutton <[EMAIL PROTECTED]> wrote: > > 100% agree :) > > Doxygen docs are good in Java where there is only OO. In C++, I > > like to > > see thing like Boost.MultiIndex reference section. > > To be honest, I find Javadoc'd documentation entirely unreadable and > pretty far from helpful.
I can never tell what's important in a Javadoc, and they often seem to go on forever. Of course, that's assuming I can actually find what I'm looking for, which is rather rare unless I already know what it is. > > Independent of having a central place for std + boost concepts with > > dynamic navigation tools to aid the user, I vot to treat each standard > > C++ sublibrary as if we were documenting a boost library. > > I would like to see a "std::vector docs" with a one minute tutorial, a > > tutorial, an examples section, a reference, performance, etc. > > Tutorial-ish stuff is necessary and I agree that it would be great to > have little five-minute tutorials, but they need to be separate from > the reference docs. Reference material needs to be both concise and > precise. Tutorials, introductions, and/or articles have a lot more > freedom for wordiness and getting off-topic. For example, the > std::list<> tutorial could have a great aside on "Why list.size() is > theta(n)". Having an "Official" Boost reference document for the standard library would be great. Assuming it'd be in quickbook or similar, it might even be turnable into a treeware version. It's nowhere near everything that's needed, but I can offer under some appropriate license some articles I've been writing that might make an acceptable starting point: http://gpwiki.org/index.php/C_plus_plus:Modern_C_plus_plus ~ Scott McMurray P.S. Isn't list's size only O(n), since some implementations make it theta(1)? ------------------------------------------------------------------------- This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2005. http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/ _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
