Skip to content

--generator: display a message when no documentation is available instead of silently producing no output #1410

Description

@rodrigoprimo

Is your feature request related to a problem?

Opening this issue following a private chat with @jrfnl around the time #687 was created. When --generator is used but none of the targeted sniffs has a documentation file, PHPCS produces no output at all on any of the three generators (Text, HTML, Markdown):

$ phpcs --standard=Squiz --sniffs=Squiz.Classes.ClassDeclaration --generator=Text

$

Without any feedback, users may think the command failed or that they used the CLI arguments incorrectly.

Describe the solution you'd like

PHPCS should display a message informing the user that no documentation is available for the requested sniff(s), instead of producing no output at all.

A few points worth discussing:

  • Whether the message should be written to STDOUT or to STDERR. I'm inclined to think it should go to STDERR to avoid polluting redirected output such as phpcs --generator=HTML > docs.html, but I can also see an argument for writing it to STDOUT, since this message is not strictly an error.

  • Whether this scenario should change the exit code. It currently returns 0.

  • Whether to print one summary line or one line per sniff without docs. The per-sniff variant is more informative but may be noisy for standards where many sniffs lack documentation.

  • I have read the Contribution Guidelines and this is not a support question.

  • I intend to create a pull request to implement this feature.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions