@param and @return comment doc for the code base

There is a * @return true in your patch, shouldn't it report Bool instead?

Right, but "True" is not a valid data type.
see: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutoria...

Yes, bool is the right data type to use.
If there are cases when the function does not return, you'd should add null

Wow, great work, thanks a lot!

I had a few corrections and further improvements, still, but all in all this is a great step forward, thanks!
Please see my revised patch. Unless you find some issues with it, I can commit it shortly.

Right, but "True" is not a valid data type.
see: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutoria...

Wrong, the Drupal coding standards explicitly state that true should be used in this case.
(Although the return value is pretty pointless in such a case anyways and should probably be removed.)

However, in this case it was still wrong, since the methods can also return FALSE, it was just not documented very well. (For a short time I unfortunately was a bit in love with using "iff".)

Great to hear.
Committed.
Thanks again for your work here!