On the surface of the argument, I'm thinking you're correct that the interface code docblocks do *not* need to repeat the spec requirements.
All three images seem to be the same image, though, so they are not matching your examples. CRB *about.me/ashnazg <http://about.me/ashnazg>* On Fri, Oct 12, 2018 at 11:42 AM Rasmus Schultz <[email protected]> wrote: > I'd like to point out some problems with the formal interfaces provided by > several packages belonging to the PSR standards. > > Starting with this example: > > [image: screenshot.png] > > This inspection failure (in PHP Storm) of course is bunk - and static > analysis can easily *prove* that it's bunk: since $abs_path is statically > type-hinted as string, it's a string. > > The issue here is the interface declaration: > > [image: screenshot.png] > > Interfaces (obviously) do not throw exceptions - their implementations do > that. > > The underlying issue I'm trying to highlight here, is that, as a consumer > of *implementations* of these interfaces, what I'm seeing in the > doc-blocks of most PSR interfaces and methods isn't documentation for me as > a consumer - it's documentation for the developers who implemented them. > > Here's another worse example from PSR-7's ServerRequestInterface: > > [image: screenshot.png] > > Reading this, as a consumer, I'm completely side-tracked by confusing and > misleading details, such as "This method MUST NOT update the related Cookie > header of the request instance, nor related values in the server params" - > explicit directions for implementors, of no relevance at them time when > you're consuming them. > > Interfaces shouldn't have language like this - for example, "*MUST return* > an instance that has the updated cookie values" ought to be "*Returns* an > instance that has the updated cookie values", and so on. > > So I'm highlighting two problems here: frequent misleading or incorrect > use of doc-blocks, and confusing explanations/specifications as opposed to > consumer-facing explanations/expectations. > > But it sort of comes down to the same thing - we've been treating the > interfaces as though they *are* the specification, with documentation and > doc-blocks written for implementors as opposed to consumers. > > You don't normally do that in your own interfaces, do you? > > Why do we do that in PSRs? > > -- > You received this message because you are subscribed to the Google Groups > "PHP Framework Interoperability Group" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > To view this discussion on the web visit > https://groups.google.com/d/msgid/php-fig/cbf43fce-19e9-4dc3-906c-d53d1972b81a%40googlegroups.com > <https://groups.google.com/d/msgid/php-fig/cbf43fce-19e9-4dc3-906c-d53d1972b81a%40googlegroups.com?utm_medium=email&utm_source=footer> > . > For more options, visit https://groups.google.com/d/optout. > -- You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CANsgjntyqRpxw0SoqKx32CS3fdSKrrs0e37YzpifDRzvQmaT2A%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
