cakephp/cakephp — pull request #2882 by ndm2 (2014-02-21 15:31:35+00:00)
Title: 3.0 - Docblock updates

This updates/fixes a bunch of docblock and docblock related problems like missing leading backslashes for fully qualified namespaces, parameter name typos, wrong parameter types, missing parameter tags, invalid/wrong/missing return types, unnecessary `@return` in de/constructors, etc... see also #2870

Pretty much all of this was found using automated inspections, and some of it was also modified automatically, so I most probably didn't catched everything. Also these changes aren't 100% docblock exclusive, some code was changed too, but only method arguments because of typos or mismatches with the docblock, respectively inconsistencies with other/related methods.

I left some of the problems I've found unchanged because I'm not sure how they should be handled. These problems can be split into two categories:

**1. Using `false` for optional parameters and not providing `boolean` as a type in the `@param` tag**

In some places `false` seems to be used for optional parameters, but the possible boolean value isn't set in the `@param` tag.

I'm not sure about the overall intention of the usage of `false` over `null` (seems to make sense here and there, `Inflector::_cache()` for example may actually cache `null`, not sure), also changing it may require modifying the logic, and the modified signatures would probably break things, so I haven't touched that.

Examples for it are the following methods:

```
File::read()
FixtureTask::bake()
Folder::__construct()
Folder::chmod()
Folder::create()
HtmlHelper::link()
Inflector::_cache()
NumberHelper::format()
Number::format()
```

**2. Intentionally left out `@param` tags that are defined in overwritten methods.**

It looks like Apigen is smart enough to handle this, however I'm not sure about IDEs and other documentation generators. What I can tell for sure is that NetBeans and PhpStorm have problems with it.

PhpStorms docblock inspections really do not like that, they only understand completely inherited docblocks, so one ends up with docblocks marked as errors, and in NetBeans the autocomplete description popups will lack these parameters as they are not being inherited.

Examples can be found here:

```
ApcEngine::clearGroup()
FileEngine::clearGroup()
MemcachedEngine::clearGroup()
RedisEngine::clearGroup()
WincacheEngine::clearGroup()
XcacheEngine::clearGroup()
```