Re: [Boost-docs] stl docs

From: Andrew Sutton (asutton_at_[hidden])
Date: 2007-07-20 09:13:34

> 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.

> 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)".

I think tutorial sections should come first, with reference material  
in the back.

> 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.

I think that's a pretty good idea. I was thinking something similar.

Andrew Sutton
asutton_at_[hidden]