Prototype docs sucks!

In our new super cool web 2.0 project I extensively use the JavaScript framework Prototype, because I use a lot of front-end intelligence and DOM manipulation. It is extremely useful and pretty easy to use, but there is only one problem. Some times when I need further explanation how some thing works, I tend to take a peek in the API documentation, and quite frankly it sucks.

First, I’m a long time .NET coder and I’m pretty used to the MSDN style documentation which is great once you get the hang of it. Also the Adobe LiveDocs are pretty OK (especially with the user commends below). But the guys at Prototype should spend a few seconds extra to write a proper description of the objects and functionality, AND some decent examples.
Let me give an example:
Under: http://prototypejs.org/api/element/writeAttribute
They tell you:

writeAttribute(element, attribute[, value = true]) -> HTMLElement
writeAttribute(element, attributes) -> HTMLElement
Adds, specifies or removes attributes passed as either a hash or a name/value pair.

What the hell does “attribute[, value = true])” mean? I could guess that the second argument is some Boolean value but does the *nothing*, mean??
What I was looking for in this method was actually a way to remove element attributes. I had to take a look in the source code for the writeAttribute method to realize that you pass a null or false as a value, in order to remove the element attribute as you can see here:

…
if (value === false || value === null)

        element.removeAttribute(name);
…

…and did I mention that there was no example what so ever of the different ways to create/remove attributes in this method?

Come on team Prototype. Your lib rocks, and so should your docs do!