On 7/20/07, Andrew Sutton <[EMAIL PROTECTED]> wrote: > I'm going to pick on something Jake > (Voytko) said: > > "I think we may want to split the documentation for each header into > two discrete segments: reference, and best practices" > > This is mostly in the right direction, except that there's a little > more to it. Many libraries require or provide concept documentation. > Concise, well-organized, and well-presented concepts are going to be > critical for C++ developers - more so in the future than now, perhaps.
Agree. > I would also like to make a distinction between "reference documents" > and "code-listings". There are a number of libraries that sell their > API reference material as a simple listing of header files, classes, > and functions (a la Doxygen). This is a lazy way to write docs and > isn't any better than looking at the header file. Reference documents > should have a complete (textual) description of the the function's > behaviors, its parameters, its preconditions and postconditions (if > relevant), return values, and exceptions. 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. > And then there's the examples... Each reference doc should contain a > meaningful example that illustrates best-practice use of the API. And > what I mean by "meaningul" is that examples should draw from a real > problem as much as possible. Here's the SGI example of std::vector: > > vector<int> V; > V.insert(V.begin(), 3); > assert(V.size() == 1 && V.capacity() >= 1 && V[0] == 3); > This is one of the most egregious examples I've ever read. There are > roughly 25 methods in this class and the example shows 5 - and none > of them are very useful. :P > Giving meaningful real-world examples helps > the reader connect with the material since it's showing the > usefulness of the subject in a relevant way. A good example of using > a vector might be the creation of a histogram (counting observations) > since it would rely on the random access properties provided by the > vector. 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. It is a lot of work... but we can take your approach here too. We can add stubs and let people collaborate. We can maintain two version, one public in the sandbox where anyone can add stuff. And a moderated version inside boost that takes the best things of the sandbox version. Best regards Matias ------------------------------------------------------------------------- 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
