如何从Yardoc文档中移除Rubocop禁用/启用注释？

我刚好处理过类似的需求，这里有两种可行的方案帮你解决这个问题：

一、使用现成的Yard插件 #

虽然没有官方专门针对Rubocop注释的插件，但可以用通用的代码注释清理插件适配，比如yard-strip-comments——你需要配置它只过滤包含rubocop:的注释行。如果社区维护的yard-rubocop-filter插件能找到的话，也可以直接用，不过自制插件其实更灵活可控。

二、自制Yard插件（推荐） #

自制插件可以精准过滤所有Rubocop相关注释，步骤如下：

1. 创建插件文件 #

在项目根目录下创建lib/yard/rubocop_comment_cleaner.rb，内容如下：

module YARD
  # 清理源代码中独立的Rubocop注释行
  module Handlers
    module Ruby
      class RubocopSourceCleaner < Base
        def self.before_parse(source_file)
          cleaned_source = source_file.source.gsub(
            /^\s*#\s*rubocop:(enable|disable|todo)\s+\S*\s*$/,
            ''
          )
          source_file.source = cleaned_source
        end
      end
    end
  end

  # 清理文档注释块中的Rubocop注释行
  module Templates
    module Helpers
      module RubocopDocstringCleaner
        def format_docstring(docstring)
          cleaned_lines = docstring.split("\n").reject do |line|
            line.strip.start_with?('# rubocop:') || line.include?('rubocop:')
          end
          super(cleaned_lines.join("\n"))
        end
      end
    end
  end
end

# 注册插件到Yard生命周期
YARD::Handlers::Ruby::RubocopSourceCleaner.register
YARD::Templates::Helpers::BaseHelper.include(YARD::Templates::Helpers::RubocopDocstringCleaner)

2. 配置Yard加载插件 #

如果项目有.yardopts文件，添加一行：

--plugin rubocop_comment_cleaner

如果没有这个文件，直接在运行yardoc命令时追加参数：

yardoc --plugin rubocop_comment_cleaner

3. 测试效果 #

运行yardoc生成文档后，你会发现所有# rubocop:disable ...、# rubocop:enable ...这类注释都被移除了，不会出现在最终的HTML文档里。

额外小技巧 #

如果你的Rubocop注释和文档注释混在同一个块里，比如：

# 这个方法用来处理复杂业务逻辑
# rubocop:disable Metrics/AbcSize
def my_complex_method
  # ...
end

上面的插件会自动过滤掉包含rubocop:的行，只保留真正的文档内容。

内容的提问来源于stack exchange，提问作者HMCFletch