commonquail
commented
10 years ago Let me explain the behaviour I desired:
- Tag names (e.g.
@param), types, and identifiers should support different colours, so that you can clearly distinguish the three in a case such as line 17. - The remainder should have regular comment colouring, for clarity as well as consistency.
- For some annotations the type should be optional (
@param) or nonexistent (@author). - For some annotations the identifier should be nonexistent (
@author) but it should never be optional. - An identifier should not occur as part of a type.
- Only the first identifier should be highlighted, as this is the important one.
- I am undecided about whether tags should be highlighted immediately or only when an argument is given. On one hand, if there are any tags that take no arguments they are few and far between, and the rest are not well-formed until an argument has been supplied. On the other hand, immediate highlighting gives faster feedback in the case of typos (I can never remember if it's
@returnor@returns).
You will note that this is not exactly what this changeset does. The main reason for that is that I decided the change would be too comprehensive for the gain and that the complexity wasn't worth it, but if you disagree I'd be willing to (try and) carry it out.
The first two points are most important to me. The rest express ideals that, practically speaking, do not seem necessary. This is a naive implementation that solves most of my problems, and since I wage a religious war on any @author tags I see in codebases I work on, the fact that it looks silly does not concern me.
For an alternative, more robust solution, I would probably partition tags into sets with formally definable parameters (@throws, @param) and no formally definable parameters (@author). The latter would apply no special matching to arguments. The former would have to distinguish between tags that expect only a type (@throws, @return) and tags that expect an identifier with an optional type (@param).
An alternative-alternative, less intrusive change, would seek to adjust phpDocTags and phpDocParam in such a way that they can contain at most one optional type and one optional identifier. I actually prefer that to what I did but there doesn't seem to be a way to express that a named pattern should follow directly after another pattern (e.g. /phpDocParam?phpDocIdentifier?/).
StanAngeloff
The PHPDoc annotations match the current line greedily. In addition to this making annotation arguments (e.g. type specifiers) blend in with the rest of the line it is inconsistent with any continuation lines, which take the default comment colour. This makes the PHPDoc matching a little more sophisticated, so annotation arguments and identifiers stand out.
Actual vs. expected:
This can arguably be simplified. In particular, line 18 in the screenshot takes steps to render the commas as comments rather than part of the identifier or annotation name. Since it's insane to use commas in identifier names, that complexity may not be necessary. A similar case can be made for line 21.