>-----Original Message----- >From: [EMAIL PROTECTED] >[mailto:[EMAIL PROTECTED] On Behalf Of >Andrew Sutton >Sent: 20 July 2007 13:18 >To: Boost documentation format, structure, and processing discussion >Subject: Re: [Boost-docs] stl docs
>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. 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. > >Examples of _bad practice_ could follow the "good example". These >might illustrate things like iterator invalidation. We could also >have "snippets" that show the best way to perform common tasks (like >erasing a range of elements). > >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. 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. > .. 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. > I think that's a pretty good idea. I was thinking something similar. I think that's a REALLY good idea. Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS [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
