ezsystems/ezpublish-kernel — pull request #716 by jeromegamez (2014-02-05 15:38:26+00:00)
Title: Simplified PHPDoc (invitation for a discussion)

I was researching in the code to get a clue on https://jira.ez.no/browse/EZP-22299 (hint hint :) ) I noticed something in the code's PHPDocs:

#### Unnecessary FQNs when referring to classes
The PHPDoc comments refer to the FQNs of parameters and return values although they are (mostly) already available or could be made available through the `use` statements at the top. This makes the PHPDoc quite bulky and could be simplified, so that instead of writing

```php
/**
* ...
* @return \eZ\Publish\API\Repository\Values\User\Role
**/
```

at multiple locations in the code, we could write

```php
// top of file
use eZ\Publish\API\Repository\Values\User\Role

// ...
/**
* ...
* @return Role
**/
```

This is partially already done, but not consistently.

#### Duplicated PHPDocs in derived classes
I noticed that all classes derived from the `RoleService` interface had exactly the same PHPDoc as the interface. If, some day, the documentation in the interface would change, this would require consequent changes in all derived classes. In addition to that, the files get bigger and thus not as easy to parse.

Modern IDEs and [phpdoc](http://www.phpdoc.org/) are able to display documentation of parent interfaces, classes and methods, so I see no compellent need to duplicate the PHPDoc in inherited elements. The benefits would be that we have to write less documentation and use less chars which would make the code a lot more fun to read :).

In this PR, I applied these points to the `RoleService`interface and its derived classes so that you could have a look and I hope for a vivid discussion (or none at all, because you all agree with me :D).

Cheers
:octocat: Jérôme