Fixed Some Docblocks

Just to keep everything the same:
* All short descriptions should end in `.`, `!`, or `?`, and should be followed by a blank line of comment.
* All long descriptions follow the same rules as the short descriptions
* All `@return` annotations should be separated from the `@param` annotations.

Example:
```php
    /**
     * This is the short description.
     *
     * This is the long description.
     *
     * @param string   $foo
     * @param int|null $bar
     *
     * @return string[] An array of strings
     */
```

I've also standardised the use of `@var` and `@type`. There was a mixture of these, so I went for `@var` since it's supported by more ides/text editors.
Not sure about that extra empty line here and in few other places