Nested annotations in @method
mindplay-dk opened this issue · comments
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 { ... }
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 :)
+1
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?
+1 - i lately needed that very very much - but it failed (couldnt do it at all)
Looks like this just needs to be added in the tag's section.
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.
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.
Does that imply that we should remove the "Inline PHPDoc" concept altogether?
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?
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 (
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?
(holding this issue open for a bit, since some upcoming answers might mean closing it altogether rather than requiring a new ML topic)
Closing for now... will have to reconsider Inline PHPDocs as a standalone conversation later.