Merge pull request #13 from ksss/method-argument

Check undocumented parameter

Author: ksss

Rakefile

@@ -22,7 +22,7 @@ namespace :smoke do
       { name: "meaningless_tag" }
     ],
     'YARD/MismatchName' => [
-      { name: "mismatch_name" }
+      { name: "mismatch_name", correct: true }
     ],
     'YARD/CollectionStyle' => [
       { name: "collection_style", style: "long", correct: true },
@@ -60,10 +60,8 @@ namespace :smoke do
       if content[:correct]
         corrected_path = "smoke/generated/#{with_style_name}_correct.rb"
         puts "Running #{corrected_path}"
-        actual = `#{cmd} #{corrected_path}`
-        unless JSON.parse(actual)["summary"]["offense_count"] == 0
-          errors << "Unexpected autocorrected output #{corrected_path}"
-        end
+        system("#{cmd} --autocorrect #{corrected_path}")
+        sh("git diff --exit-code #{corrected_path}")
       end
     end
 
@@ -85,7 +83,7 @@ namespace :smoke do
       if content[:correct]
         correct_path = "smoke/generated/#{with_style_name}_correct.rb"
         IO.copy_stream(rb_path, correct_path)
-        sh("#{cmd} --autocorrect #{correct_path}")
+        system("#{cmd} --autocorrect #{correct_path}")
       end
       sh("#{cmd} #{rb_path} | jq > #{json_path}")
     end

lib/rubocop/cop/yard/mismatch_name.rb

@@ -20,6 +20,7 @@ class MismatchName < Base
         include YARD::Helper
         include RangeHelp
         include DocumentationComment
+        extend AutoCorrector
 
         def on_def(node)
           return unless node.arguments?
@@ -28,7 +29,12 @@ def on_def(node)
           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 = 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|
@@ -56,16 +62,54 @@ def on_def(node)
                 parse_type(types.join(', '))
               rescue SyntaxError
                 next
-              end
+              end if types
 
-              add_offense_to_tag(comment, tag)
+              add_offense_to_tag(node, comment, tag)
+            end
+          end
+
+          # 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
+
+            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 }
@@ -80,13 +124,21 @@ def find_by_tag(preceding_lines, tag, i)
           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)

smoke/generated/mismatch_name.json

@@ -60,7 +60,7 @@
         },
         {
           "severity": "convention",
-          "message": "`opt` is not found in method arguments",
+          "message": "`opt` is not found in method arguments of [bar, opts]",
           "cop_name": "YARD/MismatchName",
           "corrected": false,
           "correctable": false,
@@ -105,12 +105,28 @@
             "line": 9,
             "column": 3
           }
+        },
+        {
+          "severity": "convention",
+          "message": "This method has argument `opts`, But not documented",
+          "cop_name": "YARD/MismatchName",
+          "corrected": false,
+          "correctable": true,
+          "location": {
+            "start_line": 17,
+            "start_column": 3,
+            "last_line": 17,
+            "last_column": 27,
+            "length": 25,
+            "line": 17,
+            "column": 3
+          }
         }
       ]
     }
   ],
   "summary": {
-    "offense_count": 6,
+    "offense_count": 7,
     "target_file_count": 1,
     "inspected_file_count": 1
   }

smoke/generated/mismatch_name_correct.rb

@@ -0,0 +1,47 @@
+class Foo
+  # @param [void] bar
+  # @param
+  # @param aaa
+  # @param [void]
+  # @option opt aaa [void]
+  # @option opts aaa
+  # @option opts aaa [void]
+  # @param [void]
+  # @param (see #route_docs)
+  # @param [Hash<Symbol=>Object] config Hash containing optional configuration
+  # @return [void]
+  # @return [void] fooo
+  def foo(bar, opts = {})
+  end
+
+  # @param [String] strings
+  # @param [Object] opts
+  # @param [Object] a
+  # @param [Array<Object>] rest
+  # @param [Hash{Symbol => Object}] kw
+  def bar(strings, opts = {}, a = nil, *rest, **kw)
+  end
+
+  # @return [void]
+  def return_only(arg)
+  end
+
+  # this is a doc
+  def doc_only(arg)
+  end
+
+  # @param (see #other)
+  def ref_only(arg)
+  end
+
+  # @param [String] arg
+  def rest_block(arg, *, **, &block)
+  end
+
+  # @param [String] arg
+  def delegate(arg, ...)
+  end
+
+  def empty_doc(arg)
+  end
+end

smoke/mismatch_name.rb

@@ -13,4 +13,31 @@ class Foo
   # @return [void] fooo
   def foo(bar, opts = {})
   end
+
+  # @param [String] strings
+  def bar(strings, opts = {}, a = nil, *rest, **kw)
+  end
+
+  # @return [void]
+  def return_only(arg)
+  end
+
+  # this is a doc
+  def doc_only(arg)
+  end
+
+  # @param (see #other)
+  def ref_only(arg)
+  end
+
+  # @param [String] arg
+  def rest_block(arg, *, **, &block)
+  end
+
+  # @param [String] arg
+  def delegate(arg, ...)
+  end
+
+  def empty_doc(arg)
+  end
 end