PSR-5: @throws tags on generator syntax

[Andreas Hennings (donquixote)]

Hello list!

I have a comment about the @throws tag. I think this would be part of the PSR-5 discussion.

## Background

On a generator function (a function with "yield" statement), a @throws tag has a special meaning:
- Calling the function itself will NOT throw an exception.

- Calling ->current(), ->valid() or ->next() on the returned object might throw an exception.

On a function with "@return \Iterator" or "@return \Traversable", which is not itself a generator, a @throws tag can mean both:

- The function itself might throw an exception.

- The ->current(), ->valid() or ->next() on the returned object might throw an exception.

## Question

Do we need a different kind of @throws tag for generators?

Or do we simply live with the ambiguity?

Or should a @throws tag be omitted if it does not apply to the function itself?

## See also

The question came up when discussing the inspection behavior in PhpStorm,

https://youtrack.jetbrains.com/issue/WI-33767

The @throws tag is currently documented here,

https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md#514-throws

-- Andreas