The problem is with sentences 2 and 3:

Returns the actual length of written data that can differ from len.
See writeFullBytes that tries to write the exact amount of specified bytes.

One could assume that, if len is greater than the available data to write, only the available data would be written and then that length( less than len ) would be returned.

Sentence 3 can be interpreted as such that, if len is greater than the available data to write and you want the write to fail with an exception, use writeFullBytes instead.

Basically, there is no way the return can be anything but len which is contrary to the documentation.