> Wow! Great Andrew... this can really fuel the standard docs project.
Yes... There was much rapid typing, and opening of files. Now, my
wrists hurt, but never before have so many empty files been committed
to such a great cause :)
> We have been informally discussing the fate of the Standard C++
> Library Boosted Documentation in our community blog.
>
> Jake and Stjepan have made some very important points.
> One in particular was a revelation for me:
I read those this morning...
> We should move further discussion here.
We could, but I actually prefer the mailing list since this
discussion is fairly on-topic. 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.
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.
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.
I'll re-post this as a comment on the blog-site just in case.
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
