Fixed some docblocks
minor #501 Fixed Some Docblocks (GrahamCampbell)

This PR was merged into the 1.0.x-dev branch.

Discussion
----------

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.

Commits
-------

1259b66 Fixed some docblocks