PHP DocBlock comments show dark red 'error' background
Closed this issue · 15 comments
As discussed in #22, when typing /** all subsequent code turns red, because DocBlock requires lines start with asterisks, and at that moment they don't.
Is that really necessary? It's perfectly valid PHP to have a comment starting /** with anything inside it. And the blocks of dark red appearing/disappearing is quite ugly UX to be honest.
It seems that it's not compulsive to end a multi-line comment.
<?php /**Just run the above code and PHP gives the following warning rather than an error.
PHP Warning: Unterminated comment starting
Hence anything after /** should be grammatically valid.
A comment is found in the syntax def file.
I think it's highlighted red to show you when PSR is broken?
I think it's okay to highlight it as invalid. You can modify the color scheme to make it more subtle (or disable altogether).
I think it's highlighted red to show you when PSR is broken?
Not everyone follows PSRs, and I don't think any PSR specifies how DocBlocks should work.
I think it's okay to highlight it as invalid.
But it's not invalid. Comments starting with /** don't have to be DocBlocks. Mainly it's annoying because it's alerting you to an error when you haven't had a chance to finish what you were writing.
You can modify the color scheme to make it more subtle (or disable altogether).
How do I do that?
But it's not invalid. Comments starting with /** don't have to be DocBlocks.
That is true. By the language default, anything starting with /* is just a block comment.
I wonder what should be done instead of highlighting these "invalid" lines and if, following that argument, phpdoc comments shouldn't have specific highlighting at all, because that would only be the next step.
How do I do that?
The section's scope is embedding.php text.html.basic ... source.php comment.block.documentation.phpdoc.php invalid.illegal.missing-asterik.phpdoc.php. You can select that reliably, for example, with the selector comment.block.documentation.phpdoc.php invalid and add an entry with it in your color scheme.
See http://docs.sublimetext.info/en/latest/reference/color_schemes.html.
if, following that argument, phpdoc comments shouldn't have specific highlighting at all
I have no problem with the PHPdoc highlighting itself, it's very useful. If a comment block is valid PHPdoc syntax then it should highlight @return etc. My issue is just with it saying there's an error, when there is no error.
My issue is just with it saying there's an error, when there is no error.
But there is, isn't there?
The document referenced by @jbrooksuk states this:
In case a DocComment spans multiple lines then every line MUST start with an asterisk (*) that SHOULD be aligned with the first asterisk of the opening clause.
If this document is not the "official" one, then I would like to see the real official document (where this is not invalid).
I'm talking about a PHP error. Omitting the asterisk is invalid phpdoc syntax, but not invalid PHP.
@FichteFoll FIG is a standards body separate from the PHP project itself that tries to define what they think formatting for PHP should look like.
PHP considers this syntax 100% valid. See http://php.net/manual/en/language.basic-syntax.comments.php. Multi line comments start with /* and end with */. Whatever is defined inside of there is up to what sort of standard you want to follow.
I don't think we want to get into the habit of trying to enforce style on users, but instead we should just highlight errors.
Ideally issues like this should be handled by a style linter for FIG-compliant PHP.
I don't think we want to get into the habit of trying to enforce style on users, but instead we should just highlight errors.
I can follow you through this argumentation. However, following this style would also raise attention to the following "conventions":
- All docstring syntaxes are optional, thus its highlighting should be removed completely.
- Considering TitleCase functions in JavaScript as classes would be wrong.
- ALL_CAPS identifiers could not be highlighted as
constant.
That is, of course, only if we would strictly follow the "only highlight actual syntax" principle, which may be a little bit harsh but is also consistent. Those conventions are kind of meta anyway.
What I suggest instead: Introduce a different scope for non-syntax breaking errors like in OP that is not as drastic as invalid in many color schemes but also noticable. And especially something that can be applied to all languages, where applicable. Usually, I would suggest something like invalid.optional or invalid.minor, but many schemes add obstrusive highlighting to invalid directly and not invalid.illegal. I wonder if this demands a new top-level scope.
The other similar and "easier" option, which you seem to be suggesting, is to only highlight conventions positively. I suppose we could do that.
(There really needs to be a page with syntax highlighting conventions about all this stuff.)
All of the examples you provide are additive. If they are incorrect, it isn't a huge deal, they may just provide a slightly different color to the user.
This "feature" forces you to style your code a specific way, or it says it is invalid and makes it borderline unreadable. This code isn't invalid PHP, so any scope applied to it containing "invalid" is wrong. Just light highlighting Python that violates PEP8 would be wrong.
Someone could create a FIG/PSR syntax and highlight violations to that if they wanted to. And I would think that would be a commendable effort. But I don't think it makes sense in the PHP syntax.
Can we do the following?
- If it's a valid DocBlock, apply the DocBlock highlighting.
- If it's invalid DocBlock, treat it as a standard PHP comment with no highlighting.
In other words, this would have @return highlighted:
/**
* @return int
*/
While this would just be grey with no other highlighting and no error highlighting:
/**
@return int
*/
I think it's a good idea to terminate the phpdoc context and continue with the regular block comment context that does not have specific highlighting when a line without an asterisk as its first character is encountered, yes.