Nested annotations in @method

[mindplay-dk]

Can we allow nested annotations in @method? (or is it already allowed? the section on @method in the current spec doesn't mention it.)

This would enable much more detailed descriptions of virtual methods, e.g.:

/**
 * @method bar {
 *     Room for documentation here
 *     @param string $foo more detailed param description here
 *     @return detailed return value description here
 * }
 */
class Foo { ... }

[mvriel]

We can expand the @method section to mention that instead of a simple description you can use an Inline PHPDoc to document the details on a method. Don't see why not, excellent suggestion :)

[e1himself]

+1

[mindplay-dk]

Perhaps related or separate issue, not sure, but the section on inline php-doc actually uses @method as the example of using inline doc-blocks.

Perhaps this example should be moved to the section on @method?

It would seem silly to repeat it - maybe it could just say something like "see documentation for @method" and link to the example instead?

[Setitch]

+1 - i lately needed that very very much - but it failed (couldnt do it at all)

[ashnazg]

Looks like this just needs to be added in the tag's section.

[neuro159]

Well. It will also need to be supported )

Is there other cases for such a syntax? it would be not nice to have ton of special cases... We see (..) for attrs, <...> for parametrised types and now this...

AND old short convention needs to be supported for ages... Do we prefer generation of longer or shorter?

I mean this is big and deserves a discussion.

[jaapio]

I do agree that we need to try to keep the number of variant small. For all tools it will be a pain to have all kinds of notations, but it will also make you it harder for developers writing php how to notate docblocks.

I think we should try to collect all variants and try to reduce them.

[ashnazg]

Does that imply that we should remove the "Inline PHPDoc" concept altogether?

[e1himself]

Is there other cases for such a syntax? it would be not nice to have ton of special cases... We see (..) for attrs, <...> for parametrised types and now this...

Do you guys think it would make sense to use spaces indentation only?

/**
 * @method bar
 *     Room for documentation here
 *     @param string $foo more detailed param description here
 *     @return detailed return value description here
 */
class Foo { ... }

or is it too alien for a C-style language?

[neuro159]

Do you guys think it would make sense to use spaces indentation only?

Please no - although we have pretty impressive Python IDE - that space-based stuff is kinda cumbersome and fragile even with a powerful tooling (

[ashnazg]

It seems to me that this all comes down to a decision on keeping the concept of "inline PHPDoc" or not... if we keep it, we can perhaps see if there are tags/scenarios where we don't want it available, though I can't think of such exceptions off the top of my head.

However, if the group thinks that implementing support for the "inline PHPDoc" isn't feasible/desirable, then taking it out of spec altogether is what we need to do.

@jaapio @mvriel did phpDocumentor 2.x get support for "inline PHPDocs" implemented?

[ashnazg]

(holding this issue open for a bit, since some upcoming answers might mean closing it altogether rather than requiring a new ML topic)

[ashnazg]

Closing for now... will have to reconsider Inline PHPDocs as a standalone conversation later.