Hi again team, If the working group has time, I'd really appreciate some feedback here. I'm more than happy to make pull requests to clarify documentation afterwards.
Thanks, Robbie On Wed, 20 Mar 2019 at 16:31, Robbie Averill <[email protected]> wrote: > 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/ > -- 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 [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/CANv6TC36Tsn0kDBbAyOVKQ9TA%3DpndFneT9Fa4ekWHkNWo_diLQ%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
