php-fig/fig-standards — pull request #120 by BenMorel (2013-05-13 21:06:16+00:00)
Title: Proposal for creating a standard for documenting types.

A good documentation is not only essential for developers who read the code, but also for advanced IDE features such as autocompletion and static code analysis.

While no official standard exists for docblock documentation, *de-facto* standards have emerged over time, the most famous being [PHPDocumentor](http://www.phpdoc.org/).

The following annotations are already supported by most, if not all documentation tools and IDE environments:

- `@var`
- `@param`
- `@return`
- `@throws`

This proposal targets the first three, and leaves `@throws` for a future proposal of its own, as some input from the community will be necessary to define a standard (in particular regarding whether or not to apply the Java checked/unchecked exception model).

Although IDE support is already good for simple type-hinted variables, such as `@var ClassName`, there is a clear lack of support for iterable variables (arrays and objects implementing the `Traversable` interface), that in turn contain other variables.

Some IDE environments, such as [PHPStorm](http://www.jetbrains.com/phpstorm/), have taken the lead, and already provide some level of support with a `ClassName[]` syntax. Unfortunately, this syntax does not allow to specify at the same time the type of the variable itself, *and* the type of the variables it contains.

This proposal introduces a standard solving this problem, inspired by the Java generics syntax, and 100% compatible with these existing syntaxes.

Please review!