Generators: display a message when no documentation is available

[lazerg]

Description

When --generator is used but none of the targeted sniffs ship a documentation file, all three generators (Text, HTML and Markdown) currently produce no output at all, which makes it look like the command failed or that the arguments were wrong. Following the discussion with @jrfnl referenced in the issue, this makes the generators print a short message to STDERR in that case instead of staying silent.

The message is sent to STDERR so it doesn't end up in redirected output such as phpcs --generator=HTML > docs.html. I kept it to a single summary line and left the exit code unchanged, but I'm happy to switch to a per-sniff message or a different stream if you'd prefer.

Suggested changelog entry

Added: the Text, HTML and Markdown documentation generators now print a message to STDERR when no documentation is available for the requested sniffs, instead of producing no output at all.

Related issues/external references

Fixes #1410

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
  • This change is only breaking for integrators, not for external standards or end-users.
• Documentation improvement

PR checklist

• I have checked there is no other PR open for the same change.
• I have read the Contribution Guidelines.
• I grant the project the right to include and distribute the code under the BSD-3-Clause license (and I have the right to grant these rights).
• I have added tests to cover my changes.
• I have verified that the code complies with the projects coding standards.
• [Required for new sniffs] I have added XML documentation for the sniff.
• I have opened a sister-PR in the documentation repository to update the Wiki.

[lazerg]

Hey @jrfnl, would you mind taking a look when you get a chance~

[jrfnl]

@lazerg Thanks for this PR. I've verified the implementation and it all looks good to me.

The message is sent to STDERR so it doesn't end up in redirected output such as phpcs --generator=HTML > docs.html. I kept it to a single summary line and left the exit code unchanged, but I'm happy to switch to a per-sniff message or a different stream if you'd prefer.

I agree with the choices you made. If needs be, we can always iterate on this.

Considering this is a new message for the CLI, I've earmarked this PR for the next minor release 4.1.0.

Thank you for contributing!

---

One more general remark: the commit messages for your PRs which I've looked at so far where very minimal (title only), while the PR description on the GH website contained all the reasoning for what is being fixed & why & why this way.

I'd like to ask you to include that information in the commit messages going forward for reasons as explained in the CONTRIBUTING guide:

Being wordy in the commit message is not a bad thing. It is greatly preferable to have the details about a fix in the commit message over just having those details in the PR description. Code hosting platforms come and go (think: SourceForge, PEAR), commit messages are here to stay, even if the code base would move to another platform at some point in the future.

[jrfnl]

Note to self: manually verified the code coverage as this was pulled while Coveralls had an outage. All good: https://coveralls.io/builds/80350495