[PSR-5] Tag for inline-including docblock section from another structural element

[Clint Priest]

I believe I've looked long and hard for a way to do this and there isn't one, nor any planned.

The use case is for inlined documentation to included in other locations.

A great example would be printf() & sprintf().

Even on the PHP website, the printf() page has a link to see the format description on the sprintf() page.

I'm sure there are plenty of other standard examples out there, and I have some personal use cases as well.

One way that might be easy/useful/flexible would be something like: (not quite ABNF or @NQABNF :)

@include {structural-reference} ":" {tag-name} [ {tag-index} | {tag-param} ]

{tag-index} : 0 based index of {tag-name}th item from {structural-reference}

{tag-param} : First parameter to the given {tag-name} from {structural-reference}

Some Examples:

• @include \sprintf:@param:format
• @include \sample:@example

Hopefully, this is a good starting point for a discussion on this?

Thanks,

-Clint