Hi everyone,
As a follower of the PSR-19 proposal for some time now, I am a little
confused and I'd like to clarify the usage of the @inheritDoc versus
{@inheritDoc} tag usage.
>From what I've read in the current version of PSR-19, here are my
understandings:
*Using @inheritDoc on its own (without braces)*
/**
* @inheritDoc
*/
public function example($foo, $bar): FooBar;
This will inherit the entire doc block from its parent method, including
extra tags e.g. @param.
*Using @inheritDoc (without braces) with extra content*
/**
* Add extra stuff to my child's doc block.
*
* @inheritDoc
*/
public function example($foo, $bar): FooBar;
This will inherit the entire doc block from its parent method while
prepending "Add extra stuff to my child's doc block" as well, including
tags e.g. @param.
*Using {@inheritDoc} (with braces)*
/**
* Add extra stuff to my child's doc block.
*
* {@inheritDoc}
*
* @param string $foo
* @param string $bar
* @return FooBar
*/
public function example($foo, $bar): FooBar;
This will *inherit the description* from the parent method's doc block,
while prepending "Add extra stuff to my child's doc block," and appending
@param tags to the end. Appending the tags in each child would be
necessary, because parent @param tags (etc) are not pulled through when
using @inheritDoc with braces.
Similarly:
/**
* {@inheritDoc}
*/
public function example($foo, $bar): FooBar;
This example will *inherit the description *from the parent method's doc
block, but nothing else - including @param and @return tags.
---
Are my examples above about how @inheritDoc and {@inheritDoc} work correct?
If so: don't you think these are confusingly close to each other? Can we
possibly discuss renaming the latter to @inheritDescription or something to
make it clearer what it does if you add (or forget to add) the braces?
If not: would someone on the working group mind clarifying where I've
misunderstood these examples? I'm more than happy to make a PR to update
the spec if needed to make these things clearer.
Thanks for reading.
Robbie
--
Robbie Averill | Senior Developer
04 978 7330
http://silverstripe.com/
--
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 php-fig+unsubscr...@googlegroups.com.
To post to this group, send email to php-fig@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/php-fig/CANv6TC2%3DuQ5Qvrog3kNsaSpuHZbGq7sVGEBVbjjm0dkJvO_wTw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
