rubocop-yard 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5f138fd3b5b0c5eb5550b368164986ba104280ebb40af21d7b8fe843105dad3
-  data.tar.gz: 2a237052e98046b9ac7ffcd72100fd1d96ad90164d8075e8f997981c73a78f98
+  metadata.gz: 903402913fde5bdf6702b4412bc6f1ab07197f5f993039c440ffd1a736b5277c
+  data.tar.gz: 31eeffd0cbd9fd26fe3cf5035784c990bea7e9296e10cbb22a36218c31064db9
 SHA512:
-  metadata.gz: fe3818daae4c2d4597a86ad8f1e1e6785a56e5c34e5e96b0b78be0b52b7cb219ce4d9f390ebac30af9ec844d5f2add8f4c7dfa7d5d4e6496543a0ab6a880980d
-  data.tar.gz: fd20c16153f50987d92fe2c5a6af00ecf1fd274d29205d57e63c8c176a314555de9f9e926ae1bad5b7c5b18bf3d1e7adcca26e8ead35b0f8eacc55744fb4cabb
+  metadata.gz: 48d2bd70f00ffd7c31e864039b77b9eabaff53e52b25c8825959c25486f024e3f3d63827ba98dc8ea5f09dd6a964e93700eaa1f88ef1ec6746d46804026bd444
+  data.tar.gz: 7f4e6010137fd5f1c55b70c9c6744f4ca194e6a44078aca0643020bd0ba1c9b43b7cec3cea1790eff025f79990cedb443e75b737d292095fba0896f5b0f17b68

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.7.0] - 2023-10-14
+
+- New feature
+    - `YARD/MismatchName`: Check undocumented argument.
+
 ## [0.6.0] - 2023-10-10
 
 - Split cop from `YARD/TagType` to

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/mismatch_name.rb

@@ -20,6 +20,7 @@ module RuboCop
         include YARD::Helper
         include RangeHelp
         include DocumentationComment
+        extend AutoCorrector
 
         def on_def(node)
           return unless node.arguments?
@@ -28,7 +29,12 @@ 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 = 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,9 +62,35 @@ module RuboCop
                 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
@@ -66,6 +98,18 @@ module RuboCop
 
         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 @@ 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)

data/lib/rubocop/yard/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module YARD
-    VERSION = "0.6.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.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - ksss
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-10 00:00:00.000000000 Z
+date: 2023-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop