PSR-19: Clarification over the use of @inheritDoc

[Robbie Averill]

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]

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