Deduplicate cop documentation and cop descriptions like rubocop-rspec

[backus]

I refactored part of our configuration a while back for rubocop-rspec and I'm pretty happy with it. See rubocop/rubocop-rspec#174. Basically, all of the cop documentation had something like this

module RuboCop
  module Cop
    module RSpec
      # Check for test expectations that can use `be` instead of `eql`
      #
      # (longer description snipped)
      #
      # (examples section snipped)
      #
      # (more long form description snipped)
      #
      class BeEql < Cop
      end
    end
  end
end

and the configuration description is subtly different for (IMO) no good reason:

RSpec/BeEql:
  Description: 'Check for expectations where `be(...)` can be used instead of `eql(...)`'
  Enabled: true

We now have a build command you can execute (bin/build_config) that will parse the YARD documentation and write the leading docstring to the configuration. This is run in CI too so these don't fall out of sync. I think this is a nice change because it removes a lot of duplicated work.

I would be happy to eventually help upstream this functionality to rubocop. It would be harder since your configuration files are heavily commented and spread across multiple config files. It still would be worth it though I think.

[bbatsov]

Yeah, something like this has been on my mind for a long time now.

The current way we do things is simply a remnant of the very early days of the project when this was a marginal concern compared to implementing more and more cops. It should definitely be improved at some point - I'd appreciate your help with it. I want the cop's source documentation to be the single source of truth for sure.

[bbatsov]

I guess we can revisit this after @Darhazer is done with the metadata epic, as those are somewhat related. That might also remove the need for inline documentation of the various options in the config file, although that'd assume that all those options are properly documented in the cop sources.

[garettarrowood]

I will take a stab at this. Feel free to assign me.

To paraphrase - this change should make the cop itself the single source of truth for descriptions.

Deliverables:

• :build_config task that updates our central config file descriptions to match cop descriptions
• :confirm_config task to be checked in CI to enforce these are in sync

---

That might also remove the need for inline documentation of the various options in the config file, although that'd assume that all those options are properly documented in the cop sources.

I think this could indeed be built on top of this logic. But probably in another PR, or multiple PRs that update cop docs with the options before making them the single source of truth for this info.

[pirj]

Unfortunately enough, due to a deficiency in LibYAML, it is impossible presently to parse and dump comments, which we have plenty in config/default.yml. So for now, extracting and keeping in sync config/default.yml basing on YARD cop code docs' description doesn't seem to be possible.

Draft PR with the changes required to extract and sync the cop description from cop's code comments.

I suggest postponing this to a later version (currently the milestone is set to 2.0).

[pirj]

Ok to remove this from Milestone 2.0, since we're blocked with this on LibYAML?