Document that disable comments can include a descriptive comment

[bensheldon]

Updates the documentation to reflect that disabling comments can include descriptive text after the cop name. This feature was introduced in #3191 and as far as I can tell is still supported.

This is only a documentation update, I'll do my best to pick the relevant tasks below 🙇🏻

---

Before submitting the PR make sure the following are checked:

• The PR relates to only one subject with a clear title and description in grammatically correct, complete sentences.
• Wrote good commit messages.
• Commit message starts with [Fix #issue-number] (if the related issue exists).
• Feature branch is up-to-date with master (if not - rebase it).
• Squashed related commits together.
• Added tests.
• Ran bundle exec rake default. It executes all tests and runs RuboCop on its own code.
• Added an entry (file) to the changelog folder named {change_type}_{change_description}.md if the new code introduces user-observable changes. See changelog entry format for details.

[bbatsov]

I'd change the wording to something like "You can also...", so it sounds like a suggestion. I think you removed the . before e.g. by accident.

[bensheldon]

👍🏻 I updated the language to be You can also include... and re-added the period.

[bensheldon]

@bbatsov I did some more digging into the git history and learned that the documentation I'm updating is actually much more recent than expected. It was introduced in 2020: #7995, whereas the behavior to allow the descriptive text was introduced in 2016.

Am I being accurate that disabling comments are intended to accept an additional "reason/comment"?

[bbatsov]

Yeah, it seems that actually that's not really supported. My bad. I keep forgetting how certain features work. @koic can add more on the topic I guess.

[koic]

#7993 was misdetecting comments as cop name, #7995 fixes that.

Perhaps I wanted to be told about not recommending any description other than cop name. So, it can be written free text comment on the same line, but it is not recommended. It's probably better to write it on a separate line.

[bbatsov]

@koic Agreed.

[bensheldon]

So, it can be written free text comment on the same line, but it is not recommended. It's probably better to write it on a separate line.

That sounds like it is a supported feature, but not recommended (very Rubocop-y 😄 ). I can try to capture that in the documentation.

Is the reason purely that it's prone-to-breakage?

I think the trailing reason comment is very useful to have on the same-line (it's visually closest to the code being commented; it could be removed via Lint/UnneededDisable; it could be parsed/reported). So I like it as a feature, but I also trust you all if you don't think it's possible to support it.

I see two options and I'd like your advice:

• Capture in the documentation that it is a feature, but it's not recommended because it's easy to mess up the parsing. I can also add some tests and attempt to make it less breakable and better define what is acceptable syntax.
• Close this PR because ultimately it's not a supported feature.

Thanks for chatting through this with me!

[bbatsov]

Is the reason purely that it's prone-to-breakage?

For me the main problem is that this makes sense only for a single cop/department being listed on the line, but what happens if you have several? And obviously it's easier to parse the directive contents if you know there's no free-form text somewhere in there.

I do get your point, however, and I wonder what's the best approach in general. Normally I put some explanatory comments before directives and that seems fine to me overall.