rubocop-yardoc 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c426a883ef24b7fbb8e51fd209e6052c093d154c5ea17266eaae980d9f31299a
-  data.tar.gz: b516cccfb30b937874169ca12a344bbb6fd12b878427ddb0bad5c05cda799903
+  metadata.gz: b85c7c55d0d3f08bf5634b5275d57a4f4951984bb49df452621ea8314a742ff9
+  data.tar.gz: 215d8421801cb366a8193d2e7b706977dbb3512ca6614e6a7f0a15b4501b784c
 SHA512:
-  metadata.gz: c74648386bcf3bd50f07f884e3530e0ef7e565fdb434a5d809883937738828c77a09ac0947c9adabb6aeb3858541793870e80a9f2eeb0ee5394d353a3fbee41d
-  data.tar.gz: 6bb39ddbef6f814afd4d863838f54fb3980e8087e0754a97734e27ac90a1f94036ff93922276a01b2ee2a313bf79cbcc2cd421a5618b5aeee4da8b47999b34f1
+  metadata.gz: 017eb5da65048d4090b71e58fc737201c6f709f7f6cbb9fb8c95a0df547eb5a20ea47f5e0eddf1f6c02893ef2a85a82228b88a1082c1d7bb0a375a1f980974f2
+  data.tar.gz: 42df0fcef20c8a6f3a6c419343e5a00ab8cd51fb24bb68012e1da624af798bc0c15b76d18b01b381e2cff79dd652e854886094df534c9196c22d5c05d2623e86

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-04
+
+### Added
+
+- cop: `Yardoc/TypesFormat` - Ensure types are separated with a comma and a space
+- cop: `Yardoc/ValidTypes` - Ensure the types are parseable by YARD
+
+### Changed
+
+Reworked parts of the code
+
 ## [0.1.0] - 2026-08-04
 
 - Initial release with following cops:

data/config/default.yml

@@ -57,6 +57,12 @@ Yardoc/TagOrder:
     - note
     - example
 
+Yardoc/TypesFormat:
+  Enabled: true
+
+Yardoc/ValidTypes:
+  Enabled: true
+
 Yardoc/YieldDocumentation:
   Enabled: true
   RequireParamDocumentation: true

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

@@ -4,11 +4,40 @@ 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
+      # @param tag_source_line [Parser::Source::Comment] Parsed first line of the tag
+      # @param types [Array<String>] Types of this parameter
+      # @param types_s [String] Original list of types, as declared in the tag line
+      # @param tag_range [Parser::Source::Range] Range for "@param" in source
+      # @param type_range [Parser::Source::Range] Range for the types position in source
+      # @param description_lines [Array<String>] All the lines composing the description
+      # @param type_pos [Integer] Position of the types declaration
+      # @param desc_pos [Integer] Position of the description declaration
+      ParameterTag = Struct.new(:name, :tag_source_line,
+                                :types, :types_s,
+                                :tag_range, :type_range,
+                                :description_lines,
+                                :type_pos, :desc_pos, keyword_init: true) do
+        # First line of description, usually the part on the "@param" line
+        #
+        # @return [String, nil]
+        def description_opening
+          description_lines.first
+        end
+      end
+
       # Returns the location of "@<tag_name>" of the `comment_line` in the
       # source buffer
       #
       # @param comment_line [Parser::Source::Comment] Comment line
       # @param tag_name     [String]                  Name of the tag
+      #
+      # @return [Parser::Source::Range]
       def start_tag_position(comment_line, tag_name)
         comment_range = comment_line.loc.expression
         at_pos        = comment_line.text.index('@')
@@ -18,27 +47,63 @@ module RuboCop
                                   comment_range.begin_pos + at_pos + tag_name.length + 1
       end
 
+      # Returns the location of the whole type definition of the `comment_line` in the
+      # source buffer
+      #
+      # @param comment_line [Parser::Source::Comment] Comment line
+      # @param types        [String]                  Actual type string without the brackets
+      #
+      # @return [Parser::Source::Range, nil] Nil when no range can be found
+      def start_type_position(comment_line, types)
+        return nil if types.empty?
+
+        comment_range = comment_line.loc.expression
+        at_pos        = comment_line.text.index('[')
+
+        Parser::Source::Range.new processed_source.buffer,
+                                  comment_range.begin_pos + at_pos,
+                                  comment_range.begin_pos + at_pos + 2 + types.length
+      end
+
       # Extracts "@param" tags and their position in comment block
       #
-      # @param node [RuboCop::AST::Node] The AST node
+      # @param node [RuboCop::AST::Node]     The AST node
+      # @param tags [Array<:param, :return>] The AST node
       #
-      # @return [Array<Hash>]
-      def param_tags_and_positions(node) # rubocop:disable Metrics/MethodLength
-        node_comments = processed_source.ast_with_comments.fetch(node, [])
-        param_tags = yard_tags(node).select { |t| t.tag_name == 'param' }
+      # @return [Array<ParameterTag>]
+      def param_tags_and_positions(node, tags: [:param]) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        comments = node_comments(node)
+        tags.map!(&:to_s)
 
         # Try to match extracted yard tags and source comments
-        param_tags.map do |param|
-          source_comment = node_comments.find { |comment| comment.text.match?(/@param\s+#{param.name}/) }
-
-          {
-            name:     param.name,
-            source:   source_comment.source,
-            comment:  source_comment,
-            yard_tag: param,
-            range:    start_tag_position(source_comment, 'param'),
-          }
-        end
+        yard_tags(node)
+          .select { |t| tags.include? t.tag_name }
+          .map do |yard_tag|
+            source_comment = case yard_tag.tag_name
+                             when 'param'
+                               comments.find { |comment| comment.text.match?(/^# @param\s+#{yard_tag.name}/) }
+                             when 'return'
+                               comments.find { |comment| comment.text.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_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_s:           types_s,
+                             tag_range:         start_tag_position(source_comment, yard_tag.tag_name),
+                             type_range:        start_type_position(source_comment, types_s),
+                             description_lines: description_lines,
+                             type_pos:          source_comment.text.index("[#{types_s}"),
+                             desc_pos:          desc_pos
+          end
       end
     end
   end

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

@@ -12,7 +12,7 @@ module RuboCop
       #
       # @return [YARD::DocstringParser, nil] Parsed docstring or nil if none found
       def yard_docstring(node)
-        comments = processed_source.ast_with_comments[node]
+        comments = node_comments(node)
         return nil if comments.nil? || comments.empty?
 
         comment_text = comments.map { |c| c.text.sub(/^#\s?/, '') }.join("\n")

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

@@ -5,6 +5,18 @@ module RuboCop
     module Yardoc
       # Base class that provides shared YARD parsing utilities for all YARD cops.
       class Base < 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.
@@ -13,8 +25,7 @@ module RuboCop
         #
         # @return [Boolean]
         def documented?(node)
-          comments = processed_source.ast_with_comments[node]
-          comments && !comments.empty?
+          node_comments(node).any?
         end
 
         # Checks whether a name matches any entry in an ignore list from cop configuration.
@@ -38,6 +49,15 @@ module RuboCop
         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/column_params.rb

@@ -36,7 +36,7 @@ module RuboCop
         #
         # @param node [RuboCop::AST::Node] The AST node
         def on_def(node)
-          param_lines = extract_param_lines(node)
+          param_lines = param_tags_and_positions(node)
           return if param_lines.empty?
 
           check_types_present(node, param_lines) unless config.for_cop('Yardoc/ParamDocumentation')['Enabled']
@@ -48,62 +48,35 @@ module RuboCop
 
         private
 
-        # Parses raw comment lines into structured param line data.
-        #
-        # @param node [RuboCop::AST::Node] The AST node
-        #
-        # @return [Array<Hash>]
-        def extract_param_lines(node) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-          param_tags_and_positions(node).filter_map do |param|
-            stripped = param[:source].sub(/^#\s*/, '')
-
-            match = stripped.match(/^@param\s+(\S+)(\s+\[([^\]]*)\])?(\s+(.*))?$/)
-            next unless match
-
-            # Use the match values as the Yardoc tag data may be formatted differently
-            {
-              range:    param[:range],
-              line:     param[:source],
-              comment:  param[:comment],
-              yard_tag: param[:yard_tag],
-              name:     match[1],
-              type:     match[3],
-              text:     match[5] || '',
-              type_col: param[:source].index('['),
-              desc_col: match[5] ? param[:source].index(match[5]) : nil,
-            }
-          end
-        end
-
         # Checks that every param has a type
         #
         # @param node        [RuboCop::AST::Node] The AST node
         # @param param_lines [Array<Hash>]        Hashes containing informations about the parameters
         def check_types_present(node, param_lines)
           param_lines.each do |pl|
-            next unless pl[:type].nil?
+            next unless pl.types.empty?
 
-            add_offense(node, message: format(MSG_TYPE_MISSING, name: pl[:name]))
+            add_offense(node, message: format(MSG_TYPE_MISSING, name: pl.name))
           end
         end
 
         # Checks for the alignment of comments types and descriptions
         #
         # @param param_lines [Array<Hash>] Hashes containing informations about the parameters
-        def check_alignment(param_lines) # rubocop:disable Metrics/MethodLength
+        def check_alignment(param_lines) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
           return if param_lines.count <= 1
 
           longest_type_pos, longest_text_pos = param_tag_bits_positions(param_lines)
 
           param_lines.each do |line|
             expected = "# @param #{line[:name]}".ljust(longest_type_pos, ' ') +
-                       "[#{line[:type]}]"
-            expected = expected.ljust(longest_text_pos, ' ') + line[:text]
+                       "[#{line.types_s}]"
+            expected = expected.ljust(longest_text_pos, ' ') + line.description_opening
 
-            next if line[:line] == expected
+            next if line.tag_source_line.text == expected
 
-            add_offense(line[:range], message: MSG_ALIGNMENT) do |corrector|
-              corrector.replace(line[:comment], expected)
+            add_offense(line.tag_range, message: MSG_ALIGNMENT) do |corrector|
+              corrector.replace(line.tag_source_line, expected)
             end
           end
         end
@@ -113,11 +86,12 @@ module RuboCop
         # @param param_lines [Array<Hash>] Hashes containing informations about the parameters
         #
         # @return [Array<Integer>] Types position, descriptions position
-        def param_tag_bits_positions(param_lines) # rubocop:disable Metrics/AbcSize
-          longest_type_pos = param_lines.max_by { |l| l[:name].length }[:name].length + 10
-          longest_text_pos = param_lines.max_by { |l| l[:name].length + (l[:type]&.length || 0) }
-          # Type may not have been defined
-          longest_text_pos = longest_text_pos[:type] ? longest_text_pos[:type].length + longest_type_pos + 3 : 0
+        def param_tag_bits_positions(param_lines)
+          # The + 10 is for "# @param " + the first char of description
+          longest_type_pos = param_lines.max_by { |l| l.name.length }.name.length + 10
+          longest_text_pos = param_lines.max_by { |l| l.types_s.length }
+          # Type may not have been defined; the  + 3 is for type brackets and the next space
+          longest_text_pos = longest_text_pos ? longest_text_pos.types_s.length + longest_type_pos + 3 : 0
 
           [longest_type_pos, longest_text_pos]
         end
@@ -129,7 +103,7 @@ module RuboCop
         def check_multiline_alignment(node, param_lines) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
           longest_text_pos = param_tag_bits_positions(param_lines)[1]
 
-          comments = processed_source.ast_with_comments[node]
+          comments = node_comments(node)
           comments.each_with_index do |comment, index|
             next unless comment.text.match?(/^# @param /)
 
@@ -148,26 +122,6 @@ module RuboCop
             end
           end
         end
-
-        # Returns lines immediately following a param line that are
-        # plain comment continuations (not new tags).
-        #
-        # @param comments   [Array<String>] All comment lines
-        # @param param_line [String]        The @param line to find continuations for
-        #
-        # @return [Array<String>] Continuation lines
-        def following_continuation_lines(comments, param_line)
-          index = comments.index(param_line)
-          return [] if index.nil?
-
-          result = []
-          comments[(index + 1)..].each do |line|
-            break unless line.match?(/^#\s{3,}/)
-
-            result << line
-          end
-          result
-        end
       end
     end
   end

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

@@ -21,18 +21,6 @@ module RuboCop
       class ParamDescriptionCasing < Base
         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 = 'First letter of a @param or @return tag should be in uppercase'
 
         # Matches a "param" tag line
@@ -46,16 +34,15 @@ module RuboCop
         def on_def(node)
           return unless documented? node
 
-          processed_source.comments
-                          .each do |line|
-                            match = line.text.match(PARAM_REGEXP) || line.text.match(RETURN_REGEXP)
-                            next unless match
+          node_comments(node).each do |line|
+            match = line.text.match(PARAM_REGEXP) || line.text.match(RETURN_REGEXP)
+            next unless match
 
-                            range = offense_range(line, match[:definition])
-                            add_offense(range) do |corrector|
-                              corrector.replace(range, match[:desc][0].upcase)
-                            end
-                          end
+            range = offense_range(line, match[:definition])
+            add_offense(range) do |corrector|
+              corrector.replace(range, match[:desc][0].upcase)
+            end
+          end
         end
 
         alias on_defs on_def

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

@@ -51,12 +51,10 @@ module RuboCop
               next
             end
 
-            if tag[:yard_tag].types.nil? || tag[:yard_tag].types.empty?
-              add_offense(tag[:range], message: format(MSG_NO_TYPE, name: param_name))
-            end
+            add_offense(tag.tag_range, message: format(MSG_NO_TYPE, name: param_name)) if tag.types.empty?
 
-            if require_description? && (tag[:yard_tag].text.nil? || tag[:yard_tag].text.strip.empty?)
-              add_offense(tag[:range], message: format(MSG_NO_DESCRIPTION, name: param_name))
+            if require_description? && tag.description_lines.empty?
+              add_offense(tag.tag_range, message: format(MSG_NO_DESCRIPTION, name: param_name))
             end
           end
 

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

@@ -27,18 +27,6 @@ module RuboCop
         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 `#`.
@@ -54,7 +42,7 @@ module RuboCop
         def on_def(node)
           return unless documented? node
 
-          doc_comment_groups.each do |group|
+          doc_comment_groups(node).each do |group|
             check_group(group)
           end
         end
@@ -65,11 +53,15 @@ module RuboCop
 
         # 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
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        #
+        # @return [Array<Parser::Source::Comment>]
+        def doc_comment_groups(node) # rubocop:disable Metrics/MethodLength
           groups = []
           current = []
 
-          processed_source.comments.each do |comment|
+          node_comments(node).each do |comment|
             # Only look at `#` style comments (not block =begin/=end)
             next unless comment.text.start_with?('#')
 

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

@@ -90,9 +90,9 @@ module RuboCop
         # @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, [])
+          comments = node_comments(node)
 
-          node_comments.filter_map do |comment|
+          comments.filter_map do |comment|
             text = comment.text
             tag  = text[/^# @((\w+)[\w\d]+)/, 1]
             next if tag.nil? || (!tag_name.nil? && tag_name != tag)

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures all types are separated by a space
+      #
+      # @example
+      #   # bad
+      #   # @param [String,nil]
+      #   def greet(name); end
+      #
+      #   # good
+      #   # @param name [String, nil] the name to greet
+      #   def greet(name); end
+      class TypesFormat < Base
+        include ParamHelp
+        include YardHelp
+
+        extend AutoCorrector
+
+        MSG = 'Types should be separated by a comma and a space'
+
+        # Executed for every method definition
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_def(node)
+          return unless documented?(node)
+
+          param_tags_and_positions(node, tags: [:param, :return]).each do |param|
+            expected = param.types.join(', ')
+
+            next if param.types_s == expected
+
+            add_offense(param.tag_range, message: MSG) do |corrector|
+              corrector.replace(param.type_range, "[#{expected}]")
+            end
+          end
+        end
+
+        alias on_defs on_def
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Yardoc
+      # Ensures all types are separated by a space
+      #
+      # Types are parsed with 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
+        include ParamHelp
+        include YardHelp
+
+        extend AutoCorrector
+
+        MSG = 'Types should be parseable by YARD'
+
+        # Executed for every method definition
+        #
+        # @param node [RuboCop::AST::Node] The AST node
+        def on_def(node)
+          return unless documented?(node)
+
+          param_tags_and_positions(node, tags: [:param, :return]).each do |param|
+            param.types.each do |type|
+              YARD::Tags::TypesExplainer::Parser.parse type
+            rescue SyntaxError
+              add_offense(param.type_range || param.tag_range, message: MSG)
+              break
+            end
+          end
+        end
+
+        alias on_defs on_def
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yardoc_cops.rb

@@ -16,4 +16,6 @@ require_relative 'yardoc/param_documentation'
 require_relative 'yardoc/separate_tags_blocks'
 require_relative 'yardoc/supported_tags'
 require_relative 'yardoc/tag_order'
+require_relative 'yardoc/types_format'
+require_relative 'yardoc/valid_types'
 require_relative 'yardoc/yield_documentation'

data/lib/rubocop/yardoc/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-yardoc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Manuel Tancoigne
@@ -94,6 +94,8 @@ files:
 - 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/types_format.rb
+- lib/rubocop/cop/yardoc/valid_types.rb
 - lib/rubocop/cop/yardoc/yield_documentation.rb
 - lib/rubocop/cop/yardoc_cops.rb
 - lib/rubocop/yardoc.rb