rubocop-yard 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5f138fd3b5b0c5eb5550b368164986ba104280ebb40af21d7b8fe843105dad3
-  data.tar.gz: 2a237052e98046b9ac7ffcd72100fd1d96ad90164d8075e8f997981c73a78f98
+  metadata.gz: 14068a711ba5d5d78e4781fcf5c19c0be34a5e606fad28768ea3570f0a9c044d
+  data.tar.gz: c2e62e57a7f060c86976d12aa4f123354e69b4a81d36ac5e6f549b9e3aa63fef
 SHA512:
-  metadata.gz: fe3818daae4c2d4597a86ad8f1e1e6785a56e5c34e5e96b0b78be0b52b7cb219ce4d9f390ebac30af9ec844d5f2add8f4c7dfa7d5d4e6496543a0ab6a880980d
-  data.tar.gz: fd20c16153f50987d92fe2c5a6af00ecf1fd274d29205d57e63c8c176a314555de9f9e926ae1bad5b7c5b18bf3d1e7adcca26e8ead35b0f8eacc55744fb4cabb
+  metadata.gz: f82cc0691592cd838775d632d2f13631a1c92182afca6442ec9876dad092bea401118272ce4e1031b286466d634583f027256250bab5a6f3dfa3da2ad8eb88ce
+  data.tar.gz: 2a2b413001d70d1450e2ed6c9b07607f1ed82e7bf2790d1e906a272d5c940fb4434117ee75a64a5f7ff70f439c2d0d2b4b5bcd8082588569b1699d353db64d38

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/config/default.yml

@@ -30,3 +30,8 @@ YARD/MismatchName:
   Description: 'Check @param and @option name and method parameters'
   Enabled: true
   VersionAdded: '0.3.0'
+  EnforcedStylePrototypeName: after
+  SupportedStylesPrototypeName:
+    - before
+    - after
+

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(node, comment, tag)
+            end
+          end
 
-              add_offense_to_tag(comment, tag)
+          # 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,41 @@ module RuboCop
 
         private
 
+        # @param [RuboCop::AST::ArgNode] argument
+        def tag_prototype(argument)
+          case argument.type
+          when :kwrestarg
+            case cop_config_prototype_name
+            when "before"
+              "@param #{argument.name} [Hash{Symbol => Object}]"
+            when "after"
+              "@param [Hash{Symbol => Object}] #{argument.name}"
+            end
+          when :restarg
+            case cop_config_prototype_name
+            when "before"
+              "@param #{argument.name} [Array<Object>]"
+            when "after"
+              "@param [Array<Object>] #{argument.name}"
+            end
+          else
+            case cop_config_prototype_name
+            when "before"
+              "@param #{argument.name} [Object]"
+            when "after"
+              "@param [Object] #{argument.name}"
+            end
+          end
+        end
+
+        def cop_config_prototype_name
+          @cop_config_prototype_name ||= cop_config["EnforcedStylePrototypeName"].tap do |c|
+            unless cop_config["SupportedStylesPrototypeName"].include?(c)
+              raise "unsupported style #{c}"
+            end
+          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 +147,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.8.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.8.0
 platform: ruby
 authors:
 - ksss
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-10 00:00:00.000000000 Z
+date: 2023-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop