YARD-style directives

[pointlessone]

Is your feature request related to a problem? Please describe.

YARD doesn't provide any way to ignore comments. So a common case of wrapping a method in rubocop: disable...rubocop: enable ends up with the directive in the docs.

Describe the solution you'd like

I propose to add YARD-style directive syntax.

# Method docs go here.
# @rubocop disable Metrics/PerceivedComplexity
def create_apple_pie_from_scratch
  # ...
end
# @rubocop enable Metrics/PerceivedComplexity

This way YARD would treat it as a tag. By default the tag and its content wouldn't rendered.

We can keep the colon. It would be enough to only add an optional @ before rubocop to make it work.

Considered alternative

# @rubocop
#   rubocop: disable Metrics/PerceivedComplexity

This seem to work but looks like an obvious hack.

[jonas054]

Although I find this idea reasonable, I want to mention a couple more alternatives for your consideration.

1. Disable above the documentation comment.

# rubocop:disable Metrics/PerceivedComplexity

# Method docs go here.
def create_apple_pie_from_scratch
  # ...
end
# rubocop:enable Metrics/PerceivedComplexity

2. Use an end-of-line comment to disable.

# Method docs go here.
def create_apple_pie_from_scratch # rubocop:disable Metrics/PerceivedComplexity
  # ...
end

Each of these has its own drawbacks, but maybe they are good enough to motivate not changing anything in the implementation of disable comments?

[pointlessone]

1 is an option. It seem to work. Visually it looks like the scope it a bit wider though. There's also potential of new code added in the gap even if small.

2 I must've a weird config or I did something wrong because that one get's me Style/CommentedKeyword violation.

I totally understand why not changing things is preferred. I just wish we as a broader Ruby community settled on some common directive syntax. More and more tools use custom syntax to add meaning to semantically inert comments and it's hard to make them all compatible and play well together if you have to use more than one at a time. It fast becomes like one of those "100 languages in one file" programs.

[pointlessone]

Update: Apparently, Style/CommentedKeyword doesn't allow a space after colon. So even within RuboCop alone there's no coherent concept of a directive. 😔

[jonas054]

Ah yes, you're right. That's a bug in Style/CommentedKeyword. I will fix it.