Possibly add a @standard tag for code standard in the file doc comment?

[louisl]

Whenever I open up someone elses code I have to work out or find out if a coding standard is being used.
I'm currently adding Code Standard as a text line in my file doc comment, but I think it would be useful if it became an optional tag in the file doc comment, other applications could then pick up this tag to specify the stadard for phpcs, linters etc.

Something like:

@standard PSR-2 http://www.php-fig.org/psr/psr-2

[boenrobot]

I like the idea, though I'm not entirely convinced by the tag name. I mean @standard sounds a little too vague. It doesn't explicitly communicate it's a "coding standard" we're talking about, and in the future, it might end up referring to another sort of standard. That said, I can't think of a better name. @coding-standard may be a little too verbose, and @cs may be confusing to PHP newbies inspecting the code (though then again, the URL...).

Also, I'd personally much prefer the standard's name be after the URL, since occasionally, you'd want to describe an internal coding standard (as opposed to a common one like PSR-2), e.g.

@standard http://myproject.com/coding-standard PSR-2 + PEAR (conflicting rules resolved in favor of PSR-2)

And this makes parsing of that case much easier.

[louisl]

Thinking about it, I agree the tag @standard is too vague. @coding-standard, although verbose is extremely descriptive and unmistakable. Possibly @code-standard to make it shorter?

I didn't really think of multiple standards occurring in one document but if it were to occur then would it make more sense to have it right after the tag using bar separators?

Wouldn't that be easier to parse than having it after the url? In this format the url/comment part could be optional too. eg.

@code-standard PSR-2|PEAR http://myproject.com/coding-standard (conflicting rules resolved in favor of PSR-2)
@code-standard PSR-2
@code-standard PSR-2 http://www.php-fig.org/psr/psr-2
@code-standard My-Custom-Standard http://myproject.com/coding-standard

My hope here is in the future this could also be used to automatically set an editors or other programs coding standard. My original idea was to have this tag only once per document but I guess it could also be used as a switch to change standards through a multiple standard doc.

[boenrobot]

OK, I like @code-standard.

Wouldn't that be easier to parse than having it after the url? In this format the url/comment part could be optional too.

No. It won't be easier. In fact, if there's both a description AND a name in addition to the URL, it becomes more difficult, since ReflectionDocBlock needs to maintain 3 pieces of information instead of 2.

Besides, the same code that is currently used for @license can be reused for this tag too, if the URL is first. And in it, everything after the URL is plain text. This does not prevent the URL from being omitted, since the first token is only recognized as a URL or file path if it contains ":" (i.e. is an absolute URL, with scheme) or is surrounded with quotes... Or at least that's the plan, though that's not yet implemented (mostly because it requires modifications in both phpDocumentor and ReflectionDocBlock, and those tend to be tricky to sync).

[louisl]

Thanks for your comments and input, I guess the collaboration team need to discuss and vote it now. I'll keep an eye on this and hopefully it will gain momentum.

Regards

Louis

[jaapio]

Think this shouldn't be part of phpdocumentor. Your coding standards can be checked using other tools. phpdocumentor is not the right tool. We will improve the support for plugins so you can add your own tags and how they are handled.