rubocop-yardoc 0.1.0

data/lib/rubocop/cop/yardoc/separate_tags_blocks.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures there are blank comment lines between blocks of tags in
+      # documentation comments.
+      #
+      # @example
+      #   # bad
+      #   # Title
+      #   # @param x [Integer] desc
+      #   # @param y [Integer] desc
+      #   # @return [void]
+      #   def my_method(x, y); end
+      #
+      #   # good
+      #   # Title
+      #   #
+      #   # @param x [Integer] desc
+      #   # @param y [Integer] desc
+      #   #
+      #   # @return [void]
+      #   def my_method(x, y); end
+      #
+      class SeparateTagsBlocks < Base
+        include RangeHelp
+        extend AutoCorrector
+
+        # Represents a comment entry (it may be a multi-line comment)
+        #
+        # @return [Struct] With :comment, :text, :tag, :line, :blank?
+        CommentEntry = Struct.new(:comment, :text, :tag, :line, :blank, keyword_init: true) do
+          # Whether the comment is empty
+          #
+          # @return [Boolean]
+          def blank?
+            blank
+          end
+        end
+
+        MSG = 'Add a blank comment line between different tag blocks.'
+
+        # Matches a comment line: captures the text after `#`.
+        # `#` with only trailing whitespace is a "blank comment line".
+        COMMENT_TEXT_RE = /\A#\s?(.*)\z/
+
+        # Matches a YARD-style tag at the start of comment text.
+        TAG_RE = /\A@(\w+)/
+
+        # Executed for each method definition
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_def(node)
+          return unless documented? node
+
+          doc_comment_groups.each do |group|
+            check_group(group)
+          end
+        end
+
+        alias on_defs on_def
+
+        private
+
+        # Returns an array of "groups", where each group is an array of
+        # consecutive comment lines that form a single doc comment block.
+        def doc_comment_groups # rubocop:disable Metrics/MethodLength
+          groups = []
+          current = []
+
+          processed_source.comments.each do |comment|
+            # Only look at `#` style comments (not block =begin/=end)
+            next unless comment.text.start_with?('#')
+
+            if current.empty? || consecutive?(current.last, comment)
+              current << comment
+            else
+              groups << current
+              current = [comment]
+            end
+          end
+
+          groups << current unless current.empty?
+          groups
+        end
+
+        # True if `comment` is on the very next line after `prev`.
+        #
+        # @param prev    [Parser::Source::Comment] Previous comment
+        # @param comment [Parser::Source::Comment] Current comment
+        #
+        # @return [Boolean]
+        def consecutive?(prev, comment)
+          comment.loc.line == prev.loc.line + 1
+        end
+
+        # Adds offenses for issues found in `comments`
+        #
+        # @param comments [Array<Parser::Source::Comment>] List of comments to check
+        def check_group(comments) # rubocop:disable Metrics/MethodLength
+          parsed = comments.map { |c| parse_comment(c) }
+
+          prev_tag = nil
+          prev_line_blank = false
+
+          parsed.each_with_index do |entry, idx|
+            if idx.positive? &&
+               entry.tag != prev_tag && !prev_line_blank &&
+               entry.tag != :text
+              # Boundary between two different blocks without a blank separator.
+              register_offense(comments[idx])
+            end
+
+            prev_tag = entry.tag
+            prev_line_blank = entry.blank?
+          end
+        end
+
+        # Makes an instance of CommentEntry from a comment
+        #
+        # @param comment [Parser::Source::Comment] Parsed source comment
+        #
+        # @return [CommentEntry] Nicer struct
+        def parse_comment(comment)
+          raw = comment.text
+          match = raw.match(COMMENT_TEXT_RE)
+          text = match ? match[1] : raw
+
+          blank = text.strip.empty?
+          tag_match = text.match(TAG_RE)
+          tag = tag_match ? tag_match[1].to_sym : :text
+
+          CommentEntry.new(comment: comment, text: text, tag: tag, line: comment.loc.line, blank: blank)
+        end
+
+        # Adds an offense for the given comment
+        #
+        # @param comment [Parser::Source::Comment] Offending comment
+        def register_offense(comment)
+          range = comment.loc.expression
+          add_offense(range) do |corrector|
+            indent = leading_indent(comment)
+            corrector.insert_before(range, "#\n#{indent}")
+          end
+        end
+
+        # Determine the indentation of the comment so the inserted blank line matches.
+        #
+        # @param comment [Parser::Source::Comment] Offending comment
+        #
+        # @return [String] Indented comment
+        def leading_indent(comment)
+          line_source = processed_source.lines[comment.loc.line - 1] || ''
+
+          line_source[/\A\s*/] || ''
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc/supported_tags.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures only supported YARD tags are used.
+      #
+      # The built-in supported tags follow the official YARD tag list.
+      #
+      # Additional tags can be whitelisted via `AdditionalTags` if they are
+      # not properly registered in Yardoc
+      # See Adding Custom Tags: https://rubydoc.info/gems/yard/file/docs/TagsArch.md#Adding_Custom_Tags
+      #
+      # Meta tags are not supported (`@!<tag>`, used when metaprogramming).
+      #
+      # @example
+      #   # bad
+      #   # @unknown_tag some value
+      #   def foo; end
+      #
+      #   # good
+      #   # @param name [String] a name
+      #   # @return [void]
+      #   def foo(name); end
+      #
+      # @example AdditionalTags: ['custom_tag']
+      #   # good
+      #   # @custom_tag some value
+      #   def foo; end
+      class SupportedTags < Base
+        include ParamHelp
+        include YardHelp
+
+        # List of the supported tags
+        #
+        # @see https://rubydoc.info/gems/yard/file/docs/Tags.md#Tag_List
+        YARD_TAGS = %w[
+          abstract api attr attr_reader attr_writer author deprecated example
+          note option overload param private raise return see since todo type
+          version yield yieldparam yieldreturn
+        ].freeze
+
+        MSG = 'Unsupported YARD tag `@%<tag>s`. Supported tags: %<supported>s.'
+
+        # Executed for each module/class/method definition (with aliases)
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_def(node)
+          docstring = yard_docstring(node)
+          return if docstring.nil?
+
+          # Valid Yardoc tags (and registered ones if any)
+          yardoc_tags = docstring.tags.map(&:tag_name)
+
+          tags_and_positions(node).filter do |pair|
+            next if legit_or_ignored_tag?(yardoc_tags, pair[:tag])
+
+            add_offense pair[:range], message: format(MSG, tag: pair[:tag], supported: supported_tags.join(', '))
+          end
+        end
+
+        alias on_defs   on_def
+        alias on_module on_def
+        alias on_class  on_def
+
+        private
+
+        # List of Yard allowed tags and additional ones
+        def supported_tags
+          YARD_TAGS + Array(cop_config['AdditionalTags'])
+        end
+
+        # Invalid Yardoc tags still allowed
+        def additional_tags
+          Array(cop_config['AdditionalTags'])
+        end
+
+        # Checks a tag against tags found by Yardoc and the ignore list
+        #
+        # @param yardoc_tags [Array<String>] List of tags extracted from the source
+        # @param tag         [String]        Tag to check
+        #
+        # @return            [Boolean]
+        def legit_or_ignored_tag?(yardoc_tags, tag)
+          yardoc_tags.include?(tag) || ignored?(tag, additional_tags)
+        end
+
+        # Extract all tags and their position from the comment block
+        #
+        # @param node     [RuboCop::AST::Node] The AST node to find docs for
+        # @param tag_name [String, nil]        Optional tag to filter
+        def tags_and_positions(node, tag_name = nil)
+          node_comments = processed_source.ast_with_comments.fetch(node, [])
+
+          node_comments.filter_map do |comment|
+            text = comment.text
+            tag  = text[/^# @((\w+)[\w\d]+)/, 1]
+            next if tag.nil? || (!tag_name.nil? && tag_name != tag)
+
+            {
+              tag:   tag,
+              range: start_tag_position(comment, tag),
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc/tag_order.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures YARD tags appear in the configured order.
+      #
+      # Override with the `Order` config option.
+      #
+      # @example
+      #   # bad
+      #   # @return [void]
+      #   # @param name [String] a name
+      #   def foo(name); end
+      #
+      #   # good
+      #   # @param name [String] a name
+      #   # @return [void]
+      #   def foo(name); end
+      #
+      # @example Order: [return, param]
+      #   # bad
+      #   # @param name [String] a name
+      #   # @return [void]
+      #   def foo(name); end
+      #
+      #   # good
+      #   # @return [void]
+      #   # @param name [String] a name
+      #   def foo(name); end
+      class TagOrder < Base
+        include YardHelp
+
+        MSG = 'YARD tags are out of order. Expected order: %<order>s. Found `@%<current>s` after `@%<previous>s`.'
+
+        # Default expected order corresponding to the "Order" option
+        DEFAULT_ORDER = %w[param option yieldparam yieldreturn return raise see since deprecated note example].freeze
+
+        # Executed for every module/class/method definition (with aliases)
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_def(node) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+          tags = yard_tags(node)
+          return if tags.empty?
+
+          tag_names = tags.map(&:tag_name).select { |t| order.include?(t) }
+
+          tag_names.each_cons(2) do |prev_tag, curr_tag|
+            prev_idx = order.index(prev_tag)
+            curr_idx = order.index(curr_tag)
+
+            # Unknown tags (not in order list) are skipped
+            next if prev_idx.nil? || curr_idx.nil?
+            next if curr_idx >= prev_idx
+
+            add_offense(
+              node,
+              message: format(
+                MSG,
+                order:    order.map { |t| "@#{t}" }.join(', '),
+                current:  curr_tag,
+                previous: prev_tag
+              )
+            )
+
+            break
+          end
+        end
+
+        alias on_defs   on_def
+        alias on_module on_def
+        alias on_class  on_def
+
+        private
+
+        # Order configuration
+        def order
+          cop_config.fetch('Order', DEFAULT_ORDER)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc/yield_documentation.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures methods that yield a block document it with @yield.
+      #
+      # Also checks for @yieldparam when the yield passes arguments,
+      # and @yieldreturn when the yield's return value is used.
+      #
+      # @example RequireParamDocumentation: true (default)
+      #   # bad
+      #   def each
+      #     yield item
+      #   end
+      #
+      #   # good
+      #   # @yield [item] iterates over items
+      #   # @yieldparam item [Object] the current item
+      #   def each
+      #     yield item
+      #   end
+      #
+      # @example RequireParamDocumentation: false
+      #   # bad (no yield documentation)
+      #   def each
+      #     yield item
+      #   end
+      #
+      #   # good (ignored missing param documentation)
+      #   # @yield [item] iterates over items
+      #   def each
+      #     yield item
+      #   end
+      class YieldDocumentation < Base
+        include YardHelp
+
+        MSG_YIELD       = 'Method yields a block but is missing a @yield tag.'
+        MSG_YIELDPARAM  = 'Method yields with arguments but is missing @yieldparam tags.'
+
+        # Executed for every method definition
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_def(node)
+          return unless yields?(node)
+          return unless documented?(node)
+
+          tags = yard_tags(node)
+
+          unless tags.any? { |t| t.tag_name == 'yield' }
+            add_offense(node, message: MSG_YIELD)
+            return
+          end
+
+          check_yieldparams(node, tags) if require_param_documentation?
+        end
+
+        alias on_defs on_def
+
+        private
+
+        # Whether the node yields something in its body
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        #
+        # @return [Boolean]
+        def yields?(node)
+          node.each_descendant(:yield).any?
+        end
+
+        # Whether the documntation is needed for parameters
+        #
+        # @return [Boolean]
+        def require_param_documentation?
+          cop_config.fetch('RequireParamDocumentation', true)
+        end
+
+        # Checks if current node uses a block parameter an has a "yieldparams" tag
+        #
+        # @param node [RuboCop::AST::Node]     The AST node
+        # @param tags [Array<YARD::Tags::Tag>] Tags of the node
+        def check_yieldparams(node, tags)
+          yield_args = node.each_descendant(:yield).flat_map(&:children)
+          return if yield_args.empty?
+
+          yieldparam_tags = tags.select { |t| t.tag_name == 'yieldparam' }
+          return if yieldparam_tags.size >= yield_args.size
+
+          add_offense(node, message: MSG_YIELDPARAM)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc_cops.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'mixin/node_name_help'
+require_relative 'mixin/param_help'
+require_relative 'mixin/yard_help'
+
+require_relative 'yardoc/base'
+
+require_relative 'yardoc/class_description'
+require_relative 'yardoc/column_params'
+require_relative 'yardoc/constant_description'
+require_relative 'yardoc/method_description'
+require_relative 'yardoc/module_description'
+require_relative 'yardoc/param_description_casing'
+require_relative 'yardoc/param_documentation'
+require_relative 'yardoc/separate_tags_blocks'
+require_relative 'yardoc/supported_tags'
+require_relative 'yardoc/tag_order'
+require_relative 'yardoc/yield_documentation'

data/lib/rubocop/yardoc/plugin.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'lint_roller'
+require_relative 'version'
+
+module RuboCop
+  module Yardoc
+    # A plugin that integrates RuboCop Yardoc with RuboCop's plugin system.
+    class Plugin < LintRoller::Plugin
+      # Information about the plugin
+      def about
+        LintRoller::About.new(
+          name:        'rubocop-yardoc',
+          version:     RuboCop::Yardoc::VERSION,
+          homepage:    '__FIXME__',
+          description: 'A collection of RuboCop cops to check for Yardoc documentation.'
+        )
+      end
+
+      # Whether the plugin can run in given context
+      #
+      # @param context [LintRoller::Context] Execution context
+      def supported?(context)
+        context.engine == :rubocop
+      end
+
+      # Rules configuration
+      #
+      # @param _context [LintRoller::Context] Execution context
+      def rules(_context)
+        project_root = Pathname.new(__dir__).join('../../..')
+
+        ConfigObsoletion.files << project_root.join('config', 'obsoletion.yml')
+
+        LintRoller::Rules.new(type: :path, config_format: :rubocop, value: project_root.join('config', 'default.yml'))
+      end
+    end
+  end
+end

data/lib/rubocop/yardoc/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Yardoc
+    # Library version
+    VERSION = '0.1.0'
+  end
+end

data/lib/rubocop/yardoc.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RuboCop
+  # RuboCop Yardoc project namespace.
+  module Yardoc
+  end
+end

data/lib/rubocop-yardoc.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'rubocop'
+require 'yard'
+
+require_relative 'rubocop/yardoc'
+require_relative 'rubocop/yardoc/version'
+require_relative 'rubocop/yardoc/plugin'
+require_relative 'rubocop/cop/yardoc_cops'

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: rubocop-yardoc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Manuel Tancoigne
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-08-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lint_roller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Provides a set of RuboCop rules to enforce comments format and improve
+  documentation
+email:
+- manu@experimentslabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- config/default.yml
+- config/obsoletion.yml
+- lib/rubocop-yardoc.rb
+- lib/rubocop/cop/mixin/node_name_help.rb
+- lib/rubocop/cop/mixin/param_help.rb
+- lib/rubocop/cop/mixin/yard_help.rb
+- lib/rubocop/cop/yardoc/base.rb
+- lib/rubocop/cop/yardoc/class_description.rb
+- lib/rubocop/cop/yardoc/column_params.rb
+- lib/rubocop/cop/yardoc/constant_description.rb
+- lib/rubocop/cop/yardoc/method_description.rb
+- lib/rubocop/cop/yardoc/module_description.rb
+- lib/rubocop/cop/yardoc/param_description_casing.rb
+- lib/rubocop/cop/yardoc/param_documentation.rb
+- lib/rubocop/cop/yardoc/separate_tags_blocks.rb
+- lib/rubocop/cop/yardoc/supported_tags.rb
+- lib/rubocop/cop/yardoc/tag_order.rb
+- lib/rubocop/cop/yardoc/yield_documentation.rb
+- lib/rubocop/cop/yardoc_cops.rb
+- lib/rubocop/yardoc.rb
+- lib/rubocop/yardoc/plugin.rb
+- lib/rubocop/yardoc/version.rb
+homepage: https://gitlab.com/experimentslabs/rubocop-yardoc
+licenses: []
+metadata:
+  licenses: MIT
+  homepage_uri: https://gitlab.com/experimentslabs/rubocop-yardoc
+  source_code_uri: https://gitlab.com/experimentslabs/rubocop-yardoc
+  changelog_uri: https://gitlab.com/experimentslabs/rubocop-yardoc/-/blob/main/README.md
+  default_lint_roller_plugin: RuboCop::Yardoc::Plugin
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: RuboCop plugin to enforce comments format
+test_files: []