[PSR-7] @throws annotations

[weierophinney]

• Added @throws annotations for all setters or methods accepting arguments that must be validated by implementors. In each case, InvalidArgumentException is specified.
• Made @params/@return/@throws order consistent, and removed empty lines between any such annotations for further consistency.
• Moved @link annotations before @params in all cases.

Based on a mailing list thread.

[Crell]

(thumbsup). Although I hate to point out that PSR-3 and PSR-6 DO define their own exceptions in their own namespace rather than using the SPL exception directly. So this would be inconsistent.

Edit: OK, really GitHub, what is the emoticon? Why must you make things difficult?

[weierophinney]

@Crell Interestingly, PSR-3 makes reference to a Psr\Log\InvalidArgumentException in the narrative, but does not actually define it, nor reference it in the interfaces in the specification document. The actual code in psr/log, however, does define one -- but it simply extends InvalidArgumentException.

And PSR-6 is still far from completion, so it's hard to say what will happen there with exceptions... meaning that this proposal has the possibility of helping set the standard.

In ZF2, we took the following approach: each component defines an exception marker interface, and then any component-specific exceptions implement that, while extending an appropriate SPL exception type. This gives the ability to:

• catch the specific exception type
• catch any component exceptions
• catch the more general SPL exception type
• catch the global Exception type

In other words, ultimate granularity.

So: my question is: should I propose a component exception marker interface as part of the proposal? Or leave it entirely to the implementor? (I'm leaning towards the latter, as there's already a lot of hubbub on the list about proposals getting too complex.)

[philsturgeon]

Conflicts ahoy. I had a look but they're a bit of a bugger. Can you sort em out?

[weierophinney]

@philsturgeon will do, and will ping when it's fixed.

[weierophinney]

@philsturgeon All conflicts fixed. :)