Line length and @type (and others)

[alexrussell]

I'm not sure it's particularly clearly defined where one can and cannot put a line break and expect a given parser to work properly. I may be wrong, of course, but as an example I have a lot of the following in my classes:

<?php
namespace X;

use Some\Quite\Long\Namespaced\ClassName;

Class Y {
    /** @type \Some\Quite\Long\Namespaced\ClassName $fooer The instance of ClassName that will be used for fooing the bar baz */
    protected $fooer;
}

There's not really much mentioned about line length in the document itself, but assuming we are to conform to PSR-1 we need to use a soft/hard line length of 80 and 120 respectively. I'm happy to attempt to conform to this in my code and comments, but I'm slightly wary of breaking PHPDoc parsers - can this line be broken? If so, how? Do I Have to leave it long or can I do something like this:

<?php
namespace X;

use Some\Quite\Long\Namespaced\ClassName;

Class Y {
    /**
     * @type \Some\Quite\Long\Namespaced\ClassName $fooer The instance of
     *     ClassName that will be used for fooing the bar baz
     */
    protected $fooer;
}

(Note I assume a line length of 80 characters for the sake of making a point, the same questions apply to 120 or any other line length.)

Is a single 4-space indentation okay? I notice a lot of PHPDoc indents up to the beginning of the description, but that'd be a bit useless for me and produce something like this:

<?php
namespace X;

use Some\Quite\Long\Namespaced\ClassName;

Class Y {
    /**
     * @type \Some\Quite\Long\Namespaced\ClassName $fooer The instance of
     *                                                    ClassName that will be
     *                                                    used for fooing the
     *                                                    bar baz
     */
    protected $fooer;
}

This has come up specifically for me with @type quite a bit, but the same goes for function/method @param and @return tags. The examples given in the document are great and suggesting correct formatting for what they describe, but none are full enough to give a clear indication of what to do in edge cases (although I'd posit that running out of line-length is actually quite common). In one section it mentions that the description for an @param should be no longer than 80 characters, but is that a hard limit for the description, or line-length? And is it total line length or the amount of character as of the beginning of the description?

The only example that appears to address breaking a line (other than in a description for a function/method) is in the @since tag where the description appears to be on the following line indented to the end of the tag name and in @throws tag where the description starts on the first line and breaks to the following line, indented by 4 spaces. There's also a weird bit in @version but it appears to not be part of the example, but a comment in the example explaining what that specific usage of the @version tag does. But I may be wrong there.

Reading the ABNF (not that I'm an expert at such things) it appears that line breaks are not allowed in tags, as a tag must end in CRLF and while it is mentioned that it may contain CHAR, I don't know if CHAR contains CRLF. Plus if that's the case, how can a parser reliably detect whether a second tag is actually a tag or simply the description (annoyingly-formatted I'll grant you) of the previous tag? Then in 5.3 it is mentioned that tag descriptions may contain line breaks, but no prescription as to how they should be applied. For @param and @return tags, the descriptions of each say that the description may span multiple lines and does not need to be delimited. I assume this means delimited in the sense of enclosing it in quotes or similar, and as such doesn't apply here. However, if that actually means something special regarding line breaks and indentation I think it needs to be made clearer.

I'm aware that at the top of the document it says that the document does not "Describe best practices or recommendations for Coding Standards on the application of the PHPDoc standard", but, due to parsers possibly interpreting things oddly, I feel that line-breaking and whitespace is quite important to go in the spec so that implementors don't attempt to interpret how it should work and end up differing. Precedent here is the rules of formatting short description versus long description, with the prescription that a short description must end with (either a full stop and one CRLF or) two CRLFs to be considered separate from the long description.

Maybe I'm way off-base here and it's a non-issue. I'd certainly like that to be true (although a recommended practice for PHPDoc for consistency would be nice) but I'm not sure. Or maybe it's simply outside of the remit of the document, I don't know.

Sorry for the rambling issue, hopefully I've crammed in everything I've found/thought about. I'd love to hear feedback on this.

Also, an admission: I haven't written PHPDoc before PSR-5, so maybe there are extant rules from the de-facto standard that I don't know about. If this is the case, maybe it's worth including them in this document, though.

[mvriel]

Hi @alexrussell, the PSR explicitly does not mention when to apply a line break or how many spaces must be used for an indent. Because the descriptions are all markdown texts are single line breaks not represented in the parser, and are multiple subsequent spaces collapsed into one.

You can find more information in this document: http://daringfireball.net/projects/markdown/syntax

The 80-line reference that you found was merely an example how to describe a param; I have changed that example to be less ambiguous.

Regarding the ABNF; I will have to take a look into that, that may be an error in the ABNF

[alexrussell]

@mvriel got it - that commit makes more sense. It could still be seen as guiding the rules of the PHPDoc syntax rather than actually defining the method/params in the example - it may be worth considering revising the example to be nothing to do with titles, descriptions and character lengths, just to be really clear, but, of course, that's up to you.

So I think I understand what you're saying about markdown (basically Markdown doesn't really see line breaks and whitespace in the normal 'human' way so do what you want and the whitespace will collapse into a single space), and maybe when you have a look at the ABNF you'll see if I'm right, but right now as a human I can see where one @param rule ends and another begins, but I can't see anywhere a way for a parser to know that a second @param is a new parameter rather than just the test "@param" in the description of the previous, being as there are apparently no rules about line breaks and whitespace. As far as I can tell, there's nothing wrong with a 'hard' line break in the description of a parameter and that's the core issue. Example:

<?php

// ...

/**
 * Here's a thing.
 *
 * @param string $parameter This parameter does all sorts of stuff. First it can tell the method whether to use strings or arrays.
 *
 * Second, it could do whatever you want.
 * @param int $number The number.
 */
public function whatever($parameter, $number)
// ...

It's obvious to me that there are two @param tags there, but with no rules on line break endings, a parser could theoretically see that as one large @param tag whose description itself end in the text Second, it could do whatever you want @param in $number The number. (according to Markdown's rules of line breaks).

But, as I said, I'm no ABNF expert so I'm probably reading it incorrectly. If I'm honest, other bits of the ABNF also don't quite make sense to me, so maybe it either has a few other errors, or, more likely, I'm wrong.

[ashnazg]

Historically speaking (from phpDocumentor's perspective), your example there would indeed be treated as that "Second, it could..." text being included as part of the description text in the first @param. There is no use case I've seen before where loose text is allowed in between @param tags... it would simply be considered part of the first tag's description text. Nor have I seen a case where the text desscription for the second @param would appear before that @param itself.

The third original example, where the description text is aligned very far to the right, is a characteristic from the PEAR coding standard, as best I remember. So, that kind of alignment has been in use for a long time, and phpDocumentor has always treated it as if there were no line breaks or extra spaces in it. In handling that specific case, I'd probably opt to begin the text description on a second line, only indented a bit further than the @param tag itself. That way, the block of text is aligned with itself, in a way that shows it as a child of the tag, while allowing much more column space on each line. This would break the PEAR coding standard, of course, but neither PSR1 nor PSR2 put any requirements on docblocks.

[alexrussell]

I guess what everyone's trying to tell me here is "do it in whatever way makes sense to you", which I understand. I'm contriving these example on purpose to be picky, not because I actually have these exact issues, but because I just worry that in my real examples (some of which may be similar to these) I want to ensure I'm doing it right and that PHPDoc parsers (IDEs, doc generators) will get the right meaning out of what I put.

So yeah, from a reading-it-as-a-human perspective, I can see that sticking an @param after any amount of text after an existing @param will start a new param, I just worry slightly that without a formal spec on what constitutes the description of and what constitutes the end of an @param tag a machine may not. As I said, I'm not overly great at reading ABNF but it looks like there may possibly be a hole here in what constitutes CHAR in terms of @param's ending CR.

Still, it's good to know I'm not missing something that's clearly written out, and also that I'm relatively free to do what I want as long as it's not crazy.

[mvriel]

I have altered the ABNF to allow newlines in the tag descriptions and adjusted the text for a tag to make it clear that each tag should start on a new line and how it is composed.

[mvriel]

I think that I covered all questions in this issue; so to keep an overview I will be closing it