>> >> MSDN actually does a pretty good job with reference docs. That should >> probably serve as the model. > > But I find the MSDN examples are often not Standard C++ and not > Boost style, > and they are also often a bit thin, and very thinly commented.
I don't think I was being very precise about what the "model" was. It certainly isn't the code in their documents - some of that is pretty hairy and obviously targets their own infrastructure and compilers. I just meant the depth of documentation. I've found that much of it is actually fairly good. However, some of the examples can make your eyes bleed. > Personally, I'd like something more in this style, deliberately > over-commented to restate what to some seem obvious. Perhaps... > > vector<int> V; // Constructs an empty vector. > assert(V.size() == 0); // Should be zero size, > assert(V.empty == true); // and should be empty too. > V.insert(V.begin(), 3); // Increases size by 1, and inserts the > value 3 at the front. > assert(V.size() == 1); // Check size is increased by 1, and is 1. > assert(V.capacity() >= 1); // Capacity could be more than size if > reserved (or released). > assert(V.capacity() >= V.size()) // Or something is horribly wrong! > && V[0] == 3); // Check value is same as just inserted. > ... > > Provided we have colored coding so that comments are green (or > whatever bad-taste color you prefer ;-), localising the comments in > the code makes it easier to read. And ALL are compiled together. Although I'm a big fan of well-commented code, I'm not sure that the do-something-and-assert-that-it-worked style of examples effectively conveys effective usage of class or function. That's really showing the pre- and post-conditions, which should be made explicit but probably not as an example. Andrew Sutton [EMAIL PROTECTED] ------------------------------------------------------------------------- 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
