Psalm-specific tags should be ignored (or recognized if possible)

[eli-darkly]

Psalm defines a number of special docblock tags that are 1. for configuring linter behavior or providing hints to the linter that are hard to infer from the code, or 2. for declaring type signatures, just like the regular phpDocumentor tags but a bit more flexibly.

Expected behavior

I expected or at least hoped that phpDocumentor would simply ignore the tags in category 1. They are not useful in documentation. In fact they're arguably harmful in documentation: for instance, @psalm-param-out can be used to hint to the linter that even though the type of an output parameter is nullable, in actual practice it is never null; but that is not something you want to say in the docs, because the docs are supposed to describe the API in the way it was deliberately declared, not the implementation details.

The tags in category 2, like @psalm-return, provide an extended type syntax. It'd be nice if phpDocumentor understood how to parse and display such type signatures, but if it can't, that's OK and they should probably be ignored.

Actual behavior

Unless explicitly ignored in the configuration, these tags are dumped into the docs as-is under a "Tags" heading.

Steps to reproduce the problem

1. Run phpdoc in the attached project.
2. Look at docs/html/MyClass.html. You'll see that the method1 and method2 functions are showing Psalm-specific tags under a Tags header.

Your environment

• Version used: 3.1.2
• Install method: Composer
• PHP version: 7.3
• Operating system and version Ubuntu 20.04
  phpdoc-psalm-tags.zip

[mvriel]

As a rule of thumb, we do not ignore tags ourselves because userland can come up with any kind of tag and who are we to decide which to filter or not. It would also increase the burden on the project as we'd need to build some kind of list on which tags are filtered or not in a given situation.

What phpDocumentor does provide, is the means to configure which tags you want it to have filtered. See here for an example: https://github.com/phpDocumentor/phpDocumentor/blob/master/phpdoc.dist.xml#L28

While writing this, I did discover that we have not documented this feature yet. So I know what to do soon :D

[eli-darkly]

@mvriel Well, documenting that it is configurable would definitely help.

However, I am a bit confused by the rest of your response. I don't want to beat a dead horse so I won't keep arguing if you disagree, but I do want to clarify what I was trying to say:

It is of course true that "userland can come up with any kind of tag"... and that was part of the point I was trying to make. There could be any number of @ items included in a comment, as hints to the linter, or for any other purpose. But whatever their purpose is, it is clearly not phpDocumentor markup. If that information was something that the developer wanted to appear in a generated doc comment, they would have simply described that information in the text of the comment.

So it is safe to assume that it is some other kind of markup for some other build tool, and isn't relevant in generating doc comments. The reason it is in a comment block is simply that PHP doesn't have any other kind of programmatic mechanism for annotating a class (as, for instance, Java or .NET does). That's what I meant by "the docs are supposed to describe the API in the way it was deliberately declared": the purpose of this tool is to generate documentation based on 1. information that the developer has put there explicitly for phpDocumentor to read, and 2. type information that can be unambiguously inferred from the code. If I want to use some other kind of tool that has nothing to do with documentation, but it requires me to put something in a comment block, I shouldn't have to change my phpDocumentor config just to prevent that irrelevant information from getting into my docs (as long as the tags they chose do not conflict with ones that have meaning for phpDocumentor).

I feel that the answer to the question "who are we to decide which to filter or not" is simple: it's not a matter of deciding to "filter" anything, it's simply that if it is a tag that has meaning in phpDocumentor, then you do whatever is appropriate for that, and if it isn't, then there is nothing to do. In other words, there isn't a need for a "Tags" section at all. Or, if you think people might want one, there should be an option for whether to have one or not; that is, for people who are simply trying to use phpDocumentor as the equivalent of something like Javadoc and do not want the docs to be affected by whatever kind of linting instructions some other developer may have added, it should be easy to simply turn off the listing of tags and not have to specify individual ones to disable.