Fixed some docblocks
update CONTRIBUTING.md file
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
minor #506 update CONTRIBUTING.md file (keradus)

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

Discussion
----------

update CONTRIBUTING.md file

Changes due to using gh tool.
- no need to prefix PR with `bug` etc - it will make ugly automatic merge messages.
- no need to squash commits

Commits
-------

3c3e507 update CONTRIBUTING.md file
regenerate README.rst
minor #507 regenerate README.rst (keradus)

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

Discussion
----------

regenerate README.rst

Commits
-------

1fa11d7 regenerate README.rst