"Quality" of MSDN "API Documentation"

Comming back from java world to .net world
I have found the major problem with quality of "official documentation".
For .net I still consider MSDN as the main API docs (give me better if you have).
So here is sample, when I'm interested in TagBuilder.MergeAttribute method.


TagBuilder Class

http://msdn.microsoft.com/en-us/library/system.web.mvc.tagbuilder.aspx

NO PURPOSE
NO SHORT DESCRIPTION
NO METHOD LIST AVAILABLE (on the same page)

!!! EXTRA CLICK NEEDED !!!

http://msdn.microsoft.com/en-us/library/system.web.mvc.tagbuilder_members.aspx
!!! EXTRA CLICK NEEDED !!!
http://msdn.microsoft.com/en-us/library/dd505114.aspx


MergeAttribute(String, String)
Adds an attribute to the tag by using the specified key/value pair.
MergeAttribute(String, String, Boolean)
Adds an attribute to the tag by using the specified key/value pair.


SIGNATURES WITHOUT PARAMETER NAMES are quite useless (HARD TO GUES),
specially if you give the SAME DESCRIPTION to both.

!!! EXTRA CLICK NEEDED !!! (I always go for the longest signature first, second link)

http://msdn.microsoft.com/en-us/library/dd470785.aspx

replaceExisting
Type: System..::.Boolean
true to replace the existing attributes.

ok now after 3 click I know the difference between methods.

Lets see the first signature (String,String)

!!! EXTRA CLICK NEEDED (BACK) !!!
!!! EXTRA CLICK NEEDED (FIRST SIGNATURE) !!!

http://msdn.microsoft.com/en-us/library/dd460515.aspx

WHAT ABOUT BORDER CONDITIONS ?

ArgumentException Throws if the key parameter is null reference (Nothing in Visual Basic) or empty.

Ok but:

WHAT IF VALUE IS NULL ?
(exception or attr="" or not added at all or depends on attribute's (X)HTML semantics ?)
WHAT IF ATRIBUTE ALTREADY EXISTS ?
(exception or duplicated attribute or do nothing and silent exit ?)

This is only demo, this can be applied to 90% of APIs I;m browsing, not only this "fresh MVC".
In Sun's case, the newer the API, the better docs.

In MS case ?

Usually there is NONE or FEW lines on MANY MANY pages separated by MANY MANY CLICKS about:

WHY the API exist
WHAT the API does
HOW it does what is does
WHEN it fails and
WHAT it produces in BORDER CONDITIONS
DEFAULTS in inputs
THREAD SAFETY,INSTANCES and INSTANTIATION PATTERNS used by "container" ....

These are basics, so please HELP ME:
Where do you read this info ?