rubocop-yardoc 0.2.0 → 0.2.2

data/lib/rubocop/cop/mixin/param_help.rb

@@ -4,9 +4,6 @@ module RuboCop
   module Cop
     # Helper methods to work with node parameters
     module ParamHelp
-      # Matches the [<types>] part of a @param line
-      COMMENT_TYPES_REGEX = /^[^\[]+\[([^\[]*)\]/
-
       # "@param" tag with data from Yard and parsed source code
       #
       # @param name [String]  Parameter name
@@ -81,22 +78,26 @@ module RuboCop
           .map do |yard_tag|
             source_comment = case yard_tag.tag_name
                              when 'param'
-                               comments.find { |comment| comment.text.match?(/^# @param\s+#{yard_tag.name}/) }
+                               comments.find do |comment|
+                                 comment.text.strip.match?(/^# @param\s+#{yard_tag.name}(\s|$)/)
+                               end
                              when 'return'
-                               comments.find { |comment| comment.text.match?(/^# @return\s+/) }
+                               comments.find { |comment| comment.text.strip.match?(/^# @return\s+/) }
                              else
                                next
                              end
             description_lines = yard_tag.text ? yard_tag.text.split("\n") : []
 
-            types_s = source_comment.text.match(COMMENT_TYPES_REGEX)
+            types = yard_tag.types || []
+            # Build the regexp with types matched by YARD so we don't have to bother with invalid brackets
+            types_s = source_comment.text.match(/\[(#{types.map { |t| Regexp.escape t }.join(',\\s*')})\]/)
             types_s = types_s ? types_s[1] : ''
 
             desc_pos = description_lines.any? ? source_comment.text.index(description_lines.first) : nil
 
             ParameterTag.new name:              yard_tag.name,
                              tag_source_line:   source_comment,
-                             types:             yard_tag.types || [],
+                             types:             types,
                              types_s:           types_s,
                              tag_range:         start_tag_position(source_comment, yard_tag.tag_name),
                              type_range:        start_type_position(source_comment, types_s),

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

@@ -9,28 +9,37 @@ module RuboCop
       #
       # @example
       #   # bad
-      #   class MyClass
-      #   end
+      #
+      #   class MyClass; end
       #
       #   # good
+      #
       #   # A useful class.
-      #   class MyClass
-      #   end
+      #   class MyClass; end
+      #
+      # @example Ignore: `['MyClass', '/Internal/', 'MyModule::MyOtherClass']`
+      #   # good (ignored with 'MyClass')
       #
-      # @example Ignore: ['MyClass', '/Internal/', 'MyModule::MyClass']
-      #   # good (ignored)
       #   class MyClass; end
       #
-      #   # good (ignored)
+      #   # good (ignored with /Internal/)
+      #
       #   class MyInternalClass; end
       #
       #   module MyModule
-      #     # good (ignored)
+      #     # bad
+      #
       #     class MyCustomClass; end
-      #     # good (ignored)
+      #
+      #     # good (ignored with 'MyClass')
+      #
       #     class MyClass; end
+      #
+      #     # good (ignored with 'MyModule::MyOtherClass)
+      #
+      #     class MyOtherClass; end
       #   end
-      class ClassDescription < Base
+      class ClassDescription < YardocBase
         include NodeNameHelp
 
         MSG = 'Missing YARD documentation for class `%<name>s`.'

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

@@ -13,17 +13,21 @@ module RuboCop
       #
       # @example
       #   # bad
+      #
       #   # @param foo [String] a foo
       #   # @param longer_name [Integer] a number
       #   # @param bar [String] A multiline, non aligned
       #   #   description
+      #   def my_method(foo, longer_name, bar); end
       #
       #   # good
+      #
       #   # @param foo         [String]  a foo
       #   # @param longer_name [Integer] a number
       #   # @param bar         [String]  A multiline, aligned
       #   #                              description
-      class ColumnParams < Base
+      #   def my_method(foo, longer_name, bar); end
+      class ColumnParams < YardocBase
         extend AutoCorrector
         include ParamHelp
         include YardHelp

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

@@ -9,48 +9,59 @@ module RuboCop
       #
       # @example
       #   # bad
+      #
       #   MY_CONST = 10
       #
       #   # good
-      #   # That's 9+1
+      #
+      #   # That's 9 + 1
       #   MY_CONST = 10
       #
-      # @example Ignores: ['MY_CONST']
+      # @example Ignores: `['MY_CONST']`
       #   # bad
+      #
       #   A_CONST = 'something'
       #
       #   # good (ignored)
+      #
       #   MY_CONST = 10
       #
       #   class MyClass
       #     # good (ignored)
+      #
       #     MY_CONST
       #   end
       #
-      # @example Ignores: [/^MY_CONST/]
+      # @example Ignores: `['/^MY_CONST/']`
       #   # bad
+      #
       #   A_CONST = 'something'
       #
       #   # good (ignored)
+      #
       #   MY_CONST = 10
       #
       #   class MyClass
       #     # bad
+      #
       #     MY_CONST
       #   end
       #
-      # @example Ignores: ['MyClass::MY_CONST']
+      # @example Ignores: `['MyClass::MY_CONST']`
       #   # bad
+      #
       #   A_CONST = 'something'
       #
       #   # bad
+      #
       #   MY_CONST = 10
       #
       #   class MyClass
       #     # good (ignored)
+      #
       #     MY_CONST
       #   end
-      class ConstantDescription < Base
+      class ConstantDescription < YardocBase
         include NodeNameHelp
 
         MSG = 'Missing YARD documentation for constant `%<name>s`.'

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

@@ -3,78 +3,104 @@
 module RuboCop
   module Cop
     module Yardoc
-      # Ensures all public methods have a description.
+      # Ensures all methods have a description.
       #
       # This does not ensure parameters and other documentation, only the description
       #
       # Private/protected methods are skipped unless `DocumentPrivate: true`.
       # Methods can be ignored via `Ignore`.
       #
-      # @example
+      # @example DocumentPrivate: `true` (default)
       #   # bad
+      #
       #   def my_method; end
       #
+      #   # bad
+      #
+      #   # @param name [String] The name
+      #   def some_method(name); end
+      #
       #   # good
+      #
       #   # Does something useful.
-      #   def my_method; end
+      #   def my_other_method; end
       #
-      # @example DocumentPrivate: true
-      #   # bad
       #   private
       #
+      #   # good
+      #
+      #   # Does something useful.
+      #   # def my_other_other_method; end
+      #
+      # @example DocumentPrivate: `true`
+      #   private
+      #
+      #   # good
+      #
       #   def secret; end
       #
-      # @example Ignore: [a_method]
+      # @example Ignore: `['a_method']`
       #   # bad
+      #
       #   def something; end
       #
       #   # good (ignored)
+      #
       #   def a_method; end
       #
       #   class MyClass
       #     # good (ignored)
+      #
       #     def a_method; end
       #   end
       #
-      # @example Ignore: [/^a_m/]
+      # @example Ignore: `['/^a_m/']`
       #   # bad
+      #
       #   def something; end
       #
       #   # good (ignored)
+      #
       #   def a_method; end
       #
       #   class MyClass
       #     # good (ignored)
+      #
       #     def a_method; end
       #   end
       #
-      # @example Ignore: [MyClass::a_method]
+      # @example Ignore: `['MyClass::a_method']`
       #   # bad
+      #
       #   def something; end
       #
       #   # bad
+      #
       #   def a_method; end
       #
       #   class MyClass
       #     # good (ignored)
+      #
       #     def a_method; end
       #   end
-      class MethodDescription < Base
+      class MethodDescription < YardocBase
         include VisibilityHelp
         include NodeNameHelp
+        include YardHelp
 
         MSG = 'Missing YARD documentation for method `%<name>s`.'
 
         # Executed for each method definition
         #
         # @param node [RuboCop::AST::Node] The AST node
-        def on_def(node)
+        def on_def(node) # rubocop:disable Metrics/AbcSize
           name = node.method_name.to_s
           full_name = fully_qualified_name(node)
           full_name += "::#{name}"
           return if ignored?(name, ignore_list) || ignored?(full_name, ignore_list)
           return if skip_private? && node_visibility(node) == :private
-          return if documented?(node)
+
+          return if documented?(node) && !yard_docstring(node).text.strip.empty?
 
           add_offense(node, message: format(MSG, name: name))
         end

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

@@ -9,28 +9,36 @@ module RuboCop
       #
       # @example
       #   # bad
-      #   module MyModule
-      #   end
+      #
+      #   module MyModule; end
       #
       #   # good
-      #   # A useful module.
-      #   module MyModule
-      #   end
       #
-      # @example Ignore: ['MyModule', '/Internal/', 'MyModule::MySubModule']
-      #   # good (ignored)
+      #   # A useful module.
       #   module MyModule; end
       #
-      #   # good (ignored)
+      # @example Ignore: `['MyModule', '/Internal/', 'MyModule::MySubModule']`
+      #
+      #   # good (ignored with '/Internal/')
+      #
       #   module MyInternalModule; end
       #
-      #   module MyModule
-      #     # good (ignored)
+      #   # good (ignored with 'MyModule')
+      #
+      #   module MyModule; end
+      #
+      #   # bad
+      #
+      #   module MyOtherModule
+      #     # good (ignored with 'MyModule::MySubModule')
+      #
       #     module MySubModule; end
-      #     # good (ignored)
+      #
+      #     # good (ignored with 'MyModule')
+      #
       #     module MyModule; end
       #   end
-      class ModuleDescription < Base
+      class ModuleDescription < YardocBase
         include NodeNameHelp
 
         MSG = 'Missing YARD documentation for module `%<name>s`.'

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

@@ -9,16 +9,18 @@ module RuboCop
       #
       # @example
       #   # bad
+      #
       #   # @param x [Integer] desc
       #   # @return [void] desc
       #   def my_method(x); end
       #
       #   # good
+      #
       #   # @param x [Integer] Desc
       #   # @return [void] Desc
       #   def my_method(x); end
       #
-      class ParamDescriptionCasing < Base
+      class ParamDescriptionCasing < YardocBase
         extend AutoCorrector
 
         MSG = 'First letter of a @param or @return tag should be in uppercase'

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

@@ -8,20 +8,23 @@ module RuboCop
       # By default, each @param must include a name, type, and description.
       # Set `RequireDescription: false` to only require name and type.
       #
-      # @example RequireDescription: true (default)
+      # @example RequireDescription: `true` (default)
       #   # bad
+      #
       #   # @param name [String]
       #   def greet(name); end
       #
       #   # good
+      #
       #   # @param name [String] the name to greet
       #   def greet(name); end
       #
-      # @example RequireDescription: false
+      # @example RequireDescription: `false`
       #   # good
+      #
       #   # @param name [String]
       #   def greet(name); end
-      class ParamDocumentation < Base
+      class ParamDocumentation < YardocBase
         include ParamHelp
         include YardHelp
 

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

@@ -8,6 +8,7 @@ module RuboCop
       #
       # @example
       #   # bad
+      #
       #   # Title
       #   # @param x [Integer] desc
       #   # @param y [Integer] desc
@@ -15,6 +16,7 @@ module RuboCop
       #   def my_method(x, y); end
       #
       #   # good
+      #
       #   # Title
       #   #
       #   # @param x [Integer] desc
@@ -23,7 +25,7 @@ module RuboCop
       #   # @return [void]
       #   def my_method(x, y); end
       #
-      class SeparateTagsBlocks < Base
+      class SeparateTagsBlocks < YardocBase
         include RangeHelp
         extend AutoCorrector
 

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

@@ -14,20 +14,23 @@ module RuboCop
       # 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']
+      #   # bad
+      #
+      #   # @unknown_tag some value
+      #   def foo; end
+      #
+      # @example AdditionalTags: `['custom_tag']`
       #   # good
+      #
       #   # @custom_tag some value
       #   def foo; end
-      class SupportedTags < Base
+      class SupportedTags < YardocBase
         include ParamHelp
         include YardHelp
 

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

@@ -9,26 +9,30 @@ module RuboCop
       #
       # @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]
+      # @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
+      class TagOrder < YardocBase
         include YardHelp
 
         MSG = 'YARD tags are out of order. Expected order: %<order>s. Found `@%<current>s` after `@%<previous>s`.'

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

@@ -7,13 +7,15 @@ module RuboCop
       #
       # @example
       #   # bad
+      #
       #   # @param [String,nil]
       #   def greet(name); end
       #
       #   # good
-      #   # @param name [String, nil] the name to greet
+      #
+      #   # @param name [String, nil]
       #   def greet(name); end
-      class TypesFormat < Base
+      class TypesFormat < YardocBase
         include ParamHelp
         include YardHelp
 

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

@@ -3,19 +3,19 @@
 module RuboCop
   module Cop
     module Yardoc
-      # Ensures all types are separated by a space
-      #
-      # Types are parsed with YARD.
+      # Ensures all types are parseable by YARD.
       #
       # @example
       #   # bad
+      #
       #   # @param name [.method, Array[String]] the name to greet
       #   def greet(name); end
       #
       #   # good
+      #
       #   # @param [String, List(item, item2), Array<String>, Hash{String, Integer}, ClassName, #method, nil, true]
       #   def greet(name); end
-      class ValidTypes < Base
+      class ValidTypes < YardocBase
         include ParamHelp
         include YardHelp
 

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

@@ -8,31 +8,35 @@ module RuboCop
       # Also checks for @yieldparam when the yield passes arguments,
       # and @yieldreturn when the yield's return value is used.
       #
-      # @example RequireParamDocumentation: true (default)
+      # @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
+      # @example RequireParamDocumentation: `false`
       #   # bad (no yield documentation)
+      #
       #   def each
       #     yield item
       #   end
       #
-      #   # good (ignored missing param documentation)
+      #   # good (ignored)
+      #
       #   # @yield [item] iterates over items
       #   def each
       #     yield item
       #   end
-      class YieldDocumentation < Base
+      class YieldDocumentation < YardocBase
         include YardHelp
 
         MSG_YIELD       = 'Method yields a block but is missing a @yield tag.'

data/lib/rubocop/cop/yardoc_base.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    # Base class that provides shared YARD parsing utilities for all YARD cops.
+    class YardocBase < RuboCop::Cop::Base
+      # 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
+
+      private
+
+      # Checks whether a node has any preceding documentation comments.
+      #
+      # @param node [RuboCop::AST::Node] The AST node
+      #
+      # @return [Boolean]
+      def documented?(node)
+        node_comments(node).any?
+      end
+
+      # Checks whether a name matches any entry in an ignore list from cop configuration.
+      # Entries may be plain strings or /regexp/ strings.
+      #
+      # @param name [String]        The fully-qualified name to check
+      # @param list [Array<String>] List of names or /pattern/ strings
+      #
+      # @return [Boolean]
+      def ignored?(name, list)
+        list.any? do |pattern|
+          if pattern.start_with?('/') && pattern.end_with?('/')
+            Regexp.new(pattern[1..-2]).match?(name)
+          else
+            name == pattern
+          end
+        end
+      end
+
+      # List of symbols ignored for the cop
+      def ignore_list
+        Array(cop_config['Ignore'])
+      end
+
+      # Parsed node comments
+      #
+      # @param node [RuboCop::AST::Node] The AST node
+      #
+      # @return [Array<Parser::Source::Comment>]
+      def node_comments(node)
+        processed_source.ast_with_comments.fetch(node, [])
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc_cops.rb

@@ -4,7 +4,7 @@ require_relative 'mixin/node_name_help'
 require_relative 'mixin/param_help'
 require_relative 'mixin/yard_help'
 
-require_relative 'yardoc/base'
+require_relative 'yardoc_base'
 
 require_relative 'yardoc/class_description'
 require_relative 'yardoc/column_params'

data/lib/rubocop/yardoc/version.rb

@@ -3,6 +3,6 @@
 module RuboCop
   module Yardoc
     # Library version
-    VERSION = '0.2.0'
+    VERSION = '0.2.2'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-yardoc
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Manuel Tancoigne
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lint_roller
@@ -79,11 +79,11 @@ files:
 - README.md
 - config/default.yml
 - config/obsoletion.yml
+- cops.adoc
 - 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
@@ -97,6 +97,7 @@ files:
 - lib/rubocop/cop/yardoc/types_format.rb
 - lib/rubocop/cop/yardoc/valid_types.rb
 - lib/rubocop/cop/yardoc/yield_documentation.rb
+- lib/rubocop/cop/yardoc_base.rb
 - lib/rubocop/cop/yardoc_cops.rb
 - lib/rubocop/yardoc.rb
 - lib/rubocop/yardoc/plugin.rb