[PSR-19] Multiline descriptions for @property and @method

[Marcos Passos]

Hello folks,

I would like to propose standardizing support to multiline descriptions in magic @property and @method annotation. Not allowing it has the impact of having long lines with bad readability and no paragraph support.

What is your opinion on that?

- Marcos

[Chuck Burgess]

I don't know that I remember ever encountering any Description piece, whether for DocBlock overall or individual Tags, where multiline was prohibited.

The only arguments I've ever seen regarding multiline Tag Descriptions was about indenting the subsequent lines.

Let me know if you see any places in the PSR-5 / PSR-19 drafts that seem to prohibit them.

CRB

--
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 php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/f4cbc59b-0f6b-4a56-a018-9be377ca1ea7%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Marcos Passos]

The issue here is such "magic" annotations are single-line by nature:

/**
 * @method static Foo bar() This method has a long description that extends through several lines.
 * This line should also be included in the documentation of Foo:bar()
 */
class Foo
{
}

  

It is by no means evident that the line that follows the annotation will be included in the documentation, although I believe it should. By making it explicit in the standard, leaves no room for misinterpretation on whether it is the expected result or not.

_marcos

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CANsgjntihWVr2cCEsfMADaNgdMmS6_QhCGTFLY9iPKuVgXHh1A%40mail.gmail.com.

[Chuck Burgess]

Not really... in that sense, one could argue that *all* Tags are "single-line by nature", in that every piece of a Tag (except Description) is expected to be on its first line.  Only the Description would reasonably be expected to run multiline, and the generic Tag syntax ABNF allows for that (or at least it's supposed to).

We probably do need to highlight more frequently in the examples that multiline Descriptions are perfectly valid.  I don't remember thinking of that aspect the last time I went through the drafts and made notes to myself.

CRB
about.me/ashnazg

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/CANA3DetLvCgsa0nEuqqO3jK-50bFXKVwohu4DwoN95s29OCZ5A%40mail.gmail.com.

[Jan Tvrdík]

Multiline descriptions for tags are lot more complicated than it may intuitively seem. Writing a grammar that matches behavior that human intuitively expects is very tricky. It's not enough to just say, that multiline descriptions are allowed. For some random examples see https://github.com/phpstan/phpdoc-parser/issues/6#issuecomment-362243651.

[Larry Garfield]

In practice I don't know how we can not support multi-line tag descriptions.
Many parameter descriptions or return descriptions really do need that level
of detail, and there's hundreds of thousands of examples of it in the wild.
Even many of our own PSRs have multi-line tag descriptions.

It may be hard, but I don't think we can avoid it. We just need to put rules
around them that make them both parsable and human-comprehensible. (I know,
"just" in that sentence needs really big scare quotes. Simple, but not easy.
:-) )

--Larry Garfield

[Chuck Burgess]

Something I'd highlight is that the main discussion here revolves around the specific Description portion of tags, whereas Jan's PR example talks about multi-lining the Type portion, which is something I don't recall ever coming across before.

-1 from me on allowing for multi-line Types... this could get hairy trying to tease out actual Types without colliding with the Description when the Variable was omitted.

+1 from me on allowing for multi-line Descriptions... this only involved newlines and whitespace, since the Description is the last piece of the Tag syntax... and this kind of multi-lining has existed for years.

CRB
about.me/ashnazg

--
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 php-fig+u...@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/1725610.d5TsaTEq9S%40vulcan.

[Larry Garfield]

Yes, agreed.

Related: There's two conventions I've seen for the description on tags, mainly
on @param and @return: One puts the description on the same line as the tag,
the other puts it on the next line, indented. Both are in widespread use, but
I find the next-line version to be far far easier to read in practice.

At the very least we should permit both equally, although my personal
preference would be to go as far as recommending the next-line version.

(Mentioning it here because it's related to the topic at hand.)

--Larry Garfield

On Saturday, December 8, 2018 2:22:10 PM CST Chuck Burgess wrote:
> Something I'd highlight is that the main discussion here revolves around
> the specific Description portion of tags, whereas Jan's PR example talks
> about multi-lining the Type portion, which is something I don't recall ever
> coming across before.
>
> -1 from me on allowing for multi-line Types... this could get hairy trying
> to tease out actual Types without colliding with the Description when the
> Variable was omitted.
> +1 from me on allowing for multi-line Descriptions... this only involved
> newlines and whitespace, since the Description is the last piece of the Tag
> syntax... and this kind of multi-lining has existed for years.
>
> CRB

> *about.me/ashnazg <http://about.me/ashnazg>*