One of the reasons behind my dislike for MSDN is the lack of documention defining most of the data types used in the C++ (ms standard) library. There is only so much info you can glean from MSDN before having to dig into the library header files or other references to get a clearer understanding.
Let me give you an example, the operator[] definition for the std::vector class :
reference operator[](
size_type _Pos
);
const_reference operator[](
size_type _Pos
) const;
Doing a search for the type “reference” would produce this:
A type that provides a reference to an element in a sequence controlled by the associated container.
Remarks
The type describes a reference to an element of the sequence controlled by the associated container.
and this:
typedef typename Container::reference reference;
So exactly what a “reference” type’s expected functionality is and it’s purpose is still quite unclear although we know that a “reference” type is simply a typedef of a template typename within a type Container. (Searching for a Container type brings up a similar issue)
IMHO, the java API docs are extremely well organized compared to MSDN. Class explanations are detailed and are available for every single class I’ve come across so far. Not much need to poke around the source files at all.
It might be a language issue since C/C++ is a lot more complex and therefore harder to describe than Java. But still I think it’s really obvious that the style and explanations offered by the java API docs are orders of magnitude clearer than MSDN’s.
