rubocop-yard 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4dd27dab805f9450c5043686ad6a530235d31e2a148e1913db76288fa51a39e
-  data.tar.gz: 2820aa0509d5ff6ef0adecbc772168cd8f2b64650109feb4bfb38e810625812a
+  metadata.gz: 903402913fde5bdf6702b4412bc6f1ab07197f5f993039c440ffd1a736b5277c
+  data.tar.gz: 31eeffd0cbd9fd26fe3cf5035784c990bea7e9296e10cbb22a36218c31064db9
 SHA512:
-  metadata.gz: be2c582e52297d345a8d09f413d98e15c7724b4adbd288fa5bfa38b280e9b5c752dd549885e6ec521bcd4c9dd335a71a9210475ef585d472332c2dd30066350c
-  data.tar.gz: c239f115e44518f79edb4da03cbf54c4c3e6d66659e1ff51ede40047fb5d7af6944dd4a0e08cc8e9bad53c88ae0d7869a4071655105c40704cab44a7eda10620
+  metadata.gz: 48d2bd70f00ffd7c31e864039b77b9eabaff53e52b25c8825959c25486f024e3f3d63827ba98dc8ea5f09dd6a964e93700eaa1f88ef1ec6746d46804026bd444
+  data.tar.gz: 7f4e6010137fd5f1c55b70c9c6744f4ca194e6a44078aca0643020bd0ba1c9b43b7cec3cea1790eff025f79990cedb443e75b737d292095fba0896f5b0f17b68

data/CHANGELOG.md

@@ -1,8 +1,11 @@
 ## [Unreleased]
 
-## [0.5.0] - 2023-10-9
+## [0.7.0] - 2023-10-14
 
-- Add new cop `YARD/CollectionStyle`
+- New feature
+    - `YARD/MismatchName`: Check undocumented argument.
+
+## [0.6.0] - 2023-10-10
 
 - Split cop from `YARD/TagType` to
     - `YARD/TagTypeSyntax`

data/README.md

@@ -86,6 +86,14 @@ Check `@param` and `@option` name with method definition.
 def foo(strings, opts = {})
 ```
 
+Check undocumented argument.
+
+```
+# @param [String] strings
+^^^^^^^^^^^^^^^^^^^^^^^^^ This method has argument `opts`, But not documented
+def foo(strings, opts = {})
+```
+
 ### `YARD/MeaninglessTag`
 
 Check `@param` and `@option` with class/module or casgn

data/lib/rubocop/cop/yard/collection_style.rb

@@ -42,7 +42,7 @@ module RuboCop
       #   # good
       #   # @param [Array<String>]
       class CollectionStyle < Base
-        include YARD::CollectionHelper
+        include YARD::Helper
         include RangeHelp
         include ConfigurableEnforcedStyle
         extend AutoCorrector
@@ -62,7 +62,7 @@ module RuboCop
           docstring = ::YARD::DocstringParser.new.parse(comment.text.gsub(/\A#\s*/, ''))
           each_types_explainer(docstring) do |type, types_explainer|
             correct_type = styled_string(types_explainer)
-            unless type == correct_type
+            unless ignore_whitespace(type) == ignore_whitespace(correct_type)
               add_offense(comment, message: "`#{type}` is using #{bad_style} style syntax") do |corrector|
                 corrector.replace(comment, comment.source.sub(/\[(.*)\]/) { "[#{correct_type}]" })
               end
@@ -70,6 +70,10 @@ module RuboCop
           end
         end
 
+        def ignore_whitespace(str)
+          str.tr(' ', '')
+        end
+
         def bad_style
           if style == :long
             :short

data/lib/rubocop/cop/yard/collection_type.rb

@@ -22,7 +22,7 @@ module RuboCop
       #   # good
       #   # @param [Hash{Symbol => String}]
       class CollectionType < Base
-        include YARD::CollectionHelper
+        include YARD::Helper
         include RangeHelp
         include ConfigurableEnforcedStyle
         extend AutoCorrector
@@ -86,8 +86,7 @@ module RuboCop
             case types_explainer.name
             when 'Hash'
               if types_explainer.types.length == 2
-                # `Hash<Key, Value>` pattern is the documented hash specific syntax.
-                message = "`Hash<Key, Value>` is the documented hash specific syntax"
+                message = "`Hash<Key, Value>` is ambiguous syntax"
                 add_offense(tag_range_for_comment(comment), message: message) do |corrector|
                   hash_type = ::YARD::Tags::TypesExplainer::HashCollectionType.new(
                     'Hash',

data/lib/rubocop/cop/yard/{collection_helper.rb → helper.rb}

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module YARD
-      module CollectionHelper
+      module Helper
         def extract_tag_types(tag)
           case tag
           when ::YARD::Tags::OptionTag
@@ -13,12 +13,16 @@ module RuboCop
           end
         end
 
+        def parse_type(type)
+          ::YARD::Tags::TypesExplainer::Parser.parse(type)
+        end
+
         def each_types_explainer(docstring, &block)
           docstring.tags.each do |tag|
             types = extract_tag_types(tag)
 
             begin
-              types_explainers = ::YARD::Tags::TypesExplainer::Parser.parse(types.join(', '))
+              types_explainers = parse_type(types.join(', '))
               types.zip(types_explainers).each do |type, types_explainer|
                 block.call(type, types_explainer)
               end

data/lib/rubocop/cop/yard/mismatch_name.rb

@@ -17,8 +17,10 @@ module RuboCop
       #   def foo(bar, opts = {}, *arg)
       #   end
       class MismatchName < Base
+        include YARD::Helper
         include RangeHelp
         include DocumentationComment
+        extend AutoCorrector
 
         def on_def(node)
           return unless node.arguments?
@@ -27,32 +29,93 @@ module RuboCop
           return false unless preceding_comment?(node, preceding_lines.last)
 
           yard_docstring = preceding_lines.map { |line| line.text.gsub(/\A#\s*/, '') }.join("\n")
-          docstring = ::YARD::DocstringParser.new.parse(yard_docstring)
-          docstring.tags.each_with_index do |tag, i|
-            next unless tag.tag_name == 'param' || tag.tag_name == 'option'
-
-            comment = find_by_tag(preceding_lines, tag, i)
-            next unless comment
-
-            unless tag.name && tag.types
-              if tag.name.nil?
-                add_offense(comment, message: "No tag name is supplied in `@#{tag.tag_name}`")
-              elsif tag.types.nil?
-                add_offense(comment, message: "No types are associated with the tag in `@#{tag.tag_name}`")
+          docstring = begin
+            ::YARD::DocstringParser.new.parse(yard_docstring)
+          rescue
+            return false
+          end
+
+          return false if include_overload_tag?(docstring)
+
+          each_tags_by_docstring(['param', 'option'], docstring) do |tags|
+            tags.each_with_index do |tag, i|
+              comment = find_by_tag(preceding_lines, tag, i)
+              next unless comment
+
+              # YARD::Tags::RefTagList is not has name and types
+              next if tag.instance_of?(::YARD::Tags::RefTagList)
+
+              types = extract_tag_types(tag)
+              unless tag.name && types
+                if tag.name.nil?
+                  add_offense(comment, message: "No tag name is supplied in `@#{tag.tag_name}`")
+                elsif types.nil?
+                  add_offense(comment, message: "No types are associated with the tag in `@#{tag.tag_name}`")
+                end
+
+                next
               end
 
-              next
+              next unless node.arguments.none? { |arg_node| tag.name.to_sym == arg_node.name }
+
+              begin
+                parse_type(types.join(', '))
+              rescue SyntaxError
+                next
+              end if types
+
+              add_offense_to_tag(node, comment, tag)
             end
+          end
 
-            next unless node.arguments.none? { |arg_node| tag.name.to_sym == arg_node.name }
+          # Documentation only or just `@return` is a common form of documentation.
+          # The subsequent features will be limited to cases where both `@param` and `@option` are present.
+          unless docstring.tags.find { |tag| (tag.tag_name == 'param' && !tag.instance_of?(::YARD::Tags::RefTagList)) || tag.tag_name == 'option' }
+            return false
+          end
+          node.arguments.each do |argument|
+            next if argument.type == :blockarg
+            next if argument.name.nil?
+
+            found = docstring.tags.find do |tag|
+              next unless tag.tag_name == 'param' || tag.tag_name == 'option'
+              tag.name&.to_sym == argument.name
+            end
 
-            add_offense_to_tag(comment, tag)
+            unless found
+              comment = preceding_lines.last
+              return if part_of_ignored_node?(comment)
+              add_offense(comment, message: "This method has argument `#{argument.name}`, But not documented") do |corrector|
+                corrector.replace(
+                  comment.source_range.end,
+                  "#{comment.source_range.end.join(node.source_range.begin).source}# #{tag_prototype(argument)}"
+                )
+              end
+            end
           end
         end
         alias on_defs on_def
 
         private
 
+        # @param [RuboCop::AST::ArgNode] argument
+        def tag_prototype(argument)
+          case argument.type
+          when :kwrestarg
+            "@param [Hash{Symbol => Object}] #{argument.name}"
+          when :restarg
+            "@param [Array<Object>] #{argument.name}"
+          else
+            "@param [Object] #{argument.name}"
+          end
+        end
+
+        def each_tags_by_docstring(tag_names, docstring)
+          tag_names.each do |tag_name|
+            yield docstring.tags.select { |tag| tag.tag_name == tag_name }
+          end
+        end
+
         def find_by_tag(preceding_lines, tag, i)
           count = -1
           preceding_lines.find do |line|
@@ -61,13 +124,25 @@ module RuboCop
           end
         end
 
-        def add_offense_to_tag(comment, tag)
+        def add_offense_to_tag(node, comment, tag)
           tag_name_regexp = Regexp.new("\\b#{Regexp.escape(tag.name)}\\b")
           start_column = comment.source.index(tag_name_regexp)
           offense_start = comment.location.column + start_column
           offense_end = offense_start + tag.name.length - 1
           range = source_range(processed_source.buffer, comment.location.line, offense_start..offense_end)
-          add_offense(range, message: "`#{tag.name}` is not found in method arguments")
+          argument_names = node.arguments.map(&:name).compact
+          argument_name =
+            if argument_names.empty?
+              ''
+            else
+              " of [#{argument_names.join(', ')}]"
+            end
+          add_offense(range, message: "`#{tag.name}` is not found in method arguments#{argument_name}")
+          ignore_node(comment)
+        end
+
+        def include_overload_tag?(docstring)
+          docstring.tags.any? { |tag| tag.tag_name == "overload" }
         end
       end
     end

data/lib/rubocop/cop/yard/tag_type_syntax.rb

@@ -10,6 +10,7 @@ module RuboCop
       #   # good
       #   # @param [Integer, String]
       class TagTypeSyntax < Base
+        include YARD::Helper
         include RangeHelp
 
         def on_new_investigation
@@ -26,10 +27,10 @@ module RuboCop
         def check(comment)
           docstring = comment.text.gsub(/\A#\s*/, '')
           ::YARD::DocstringParser.new.parse(docstring).tags.each do |tag|
-            types = extract_tag_type(tag)
+            types = extract_tag_types(tag)
 
             check_syntax_error(comment) do
-              ::YARD::Tags::TypesExplainer::Parser.parse(types.join(', '))
+              parse_type(types.join(', '))
             end
           end
         end
@@ -42,15 +43,6 @@ module RuboCop
           end
         end
 
-        def extract_tag_type(tag)
-          case tag
-          when ::YARD::Tags::OptionTag
-            tag.pair.types
-          else
-            tag.types
-          end
-        end
-
         def inline_comment?(comment)
           !comment_line?(comment.source_range.source_line)
         end

data/lib/rubocop/cop/yard_cops.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'yard'
-require_relative 'yard/collection_helper'
+require_relative 'yard/helper'
 require_relative 'yard/collection_style'
 require_relative 'yard/collection_type'
 require_relative 'yard/meaningless_tag'

data/lib/rubocop/yard/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module YARD
-    VERSION = "0.5.0"
+    VERSION = "0.7.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-yard
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - ksss
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-08 00:00:00.000000000 Z
+date: 2023-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -51,9 +51,9 @@ files:
 - README.md
 - config/default.yml
 - lib/rubocop-yard.rb
-- lib/rubocop/cop/yard/collection_helper.rb
 - lib/rubocop/cop/yard/collection_style.rb
 - lib/rubocop/cop/yard/collection_type.rb
+- lib/rubocop/cop/yard/helper.rb
 - lib/rubocop/cop/yard/meaningless_tag.rb
 - lib/rubocop/cop/yard/mismatch_name.rb
 - lib/rubocop/cop/yard/tag_type_syntax.rb