rubocop-yard 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77c23358faa88b10e005e0f455dcf16283fe9fbf64c92276e5bff6bb201de43a
-  data.tar.gz: a1fb8bfe577565d31294920356f176fd9bc71b856ee7db0a11031347473602c5
+  metadata.gz: b41b5e256726136d4cd8bfc96fabd2ab0fbc37e69a84c9f29a76456f464cf519
+  data.tar.gz: 678da6e808f7b844e4bd94ab061dbf8176c1aba9c3b279a211bf040f7cba907b
 SHA512:
-  metadata.gz: 478b94fe6b6bd5f310fc5774554888a5aa0f99245cc8a13ff8f5225668e5486213eeec4f7621f84b3a4790a9989a9b03a0ebc47c848fda1e757194353d3d1049
-  data.tar.gz: debd8aa21c9d08430fd666a239e6e6114fd1dc091053f76254def0f62d37b9d1698c291c3d91ac716fc80682b07593512bd512ecd143327d3995573dacf603fb
+  metadata.gz: c14be7ae06b265ef9396bd3b2c494db30e7165cdcebd74884633053ca24a2007e367dc44bc7e8a17deec4a4c62f83eeabd3ae55bd9065ccc3b89633cf4052aee
+  data.tar.gz: f4fd229b29630192b24036fb59bc145704904a2f9142c26738a71815212fa1bf60a725a7c5b984c63a75c05ac75e31d8a6d55b238cdefce1384a4f69d449c315

data/CHANGELOG.md

@@ -1,12 +1,17 @@
 ## [Unreleased]
 
+## [0.3.0] - 2023-09-16
+
+- Add `YARD/MismatchName`
+    - Check `@param` and `@option` name with method definition
+
 ## [0.2.0] - 2023-09-14
 
-- `YARD/TagTypeSyntax`
+- `YARD/TagType`
     - Check collection tag type syntax
 
 ## [0.1.0] - 2023-09-13
 
-- Add new `YARD/TagTypeSyntax` cop
+- Add new `YARD/TagType` cop
 
 - Initial release

data/README.md

@@ -6,18 +6,30 @@ You can check YARD format in Ruby code comment by RuboCop.
 
 ## Features
 
-### `YARD/TagTypeSyntax`
+### `YARD/TagType`
 
 Check tag type syntax error.
 
 ```
-@param [Symbol|String]
-        ^^^^^^^^^^^^^ SyntaxError as YARD tag type
+# @param [Symbol|String]
+#         ^^^^^^^^^^^^^ SyntaxError as YARD tag type
 ```
 
 ```
-@param [Hash<Symbol, String>]
-        ^^^^^^^^^^^^^^^^^^^^ <Type> is the collection type syntax. Did you mean {KeyType => ValueType} or Hash{KeyType => ValueType}
+# @param [Hash<Symbol, String>]
+#         ^^^^^^^^^^^^^^^^^^^^ `<Type>` is the collection type syntax. Did you mean `{KeyType => ValueType}` or `Hash{KeyType => ValueType}`
+```
+
+### `YARD/MismatchName`
+
+Check `@param` and `@option` name with method definition.
+
+```rb
+# @param [String] string
+#                 ^^^^^^ `string` is not found in method arguments
+# @option opt bar [String]
+#         ^^^ `opt` is not found in method arguments
+def foo(strings, opts = {})
 ```
 
 ## Installation

data/config/default.yml

@@ -1,4 +1,9 @@
-YARD/TagTypeSyntax:
+YARD/TagType:
   Description: 'Check syntax for yard tag type'
   Enabled: true
-  VersionAdded: '0.1.0'
+  VersionAdded: '0.2.0'
+
+YARD/MismatchName
+  Description: 'Check @param and @option name and method parameters'
+  Enabled: true
+  VersionAdded: '0.3.0'

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module YARD
+      # @example
+      #   # bad
+      #   # @param [void] baz
+      #   # @option opt aaa [void]
+      #   def foo(bar, opts = {})
+      #   end
+      #
+      #   # good
+      #   # @param [void] bar
+      #   # @param [Array] argsa
+      #   # @option opts aaa [void]
+      #   def foo(bar, opts = {}, *arg)
+      #   end
+      class MismatchName < Base
+        include RangeHelp
+        include DocumentationComment
+
+        def on_def(node)
+          return unless node.arguments?
+
+          preceding_lines = preceding_lines(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.tags.each do |tag|
+            next unless tag.tag_name == 'param' || tag.tag_name == 'option'
+            next unless node.arguments.none? { |arg_node| tag.name.to_sym == arg_node.name }
+
+            tag_name_regexp = Regexp.new("\\b#{Regexp.escape(tag.name)}\\b")
+            comment = preceding_lines.find { |line| line.text.match?(tag_name_regexp) && line.text.include?("@#{tag.tag_name}") }
+            next unless comment
+
+            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")
+          end
+        end
+        alias on_defs on_def
+      end
+
+      private
+
+      # @param [void] aaa
+      # @option opts bbb [void]
+      def dummy(aaa, opts = {}, *)
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yard/{tag_type_syntax.rb → tag_type.rb}

@@ -22,6 +22,8 @@ module RuboCop
       #   # good
       #   @param [<String>]
       #   @param [Array<String>]
+      #   @param [List<String>]
+      #   @param [Array<(String, Fixnum, Hash)>]
       #
       #   # good
       #   @param [(String)]
@@ -30,7 +32,7 @@ module RuboCop
       #   # good
       #   @param [{KeyType => ValueType}]
       #   @param [Hash{KeyType => ValueType}]
-      class TagTypeSyntax < Base
+      class TagType < Base
         MSG = ''
         include RangeHelp # @return [void,]
 
@@ -48,6 +50,8 @@ module RuboCop
         def check(comment)
           docstring = comment.text.gsub(/\A#\s*/, '')
           ::YARD::DocstringParser.new.parse(docstring).tags.each do |tag|
+            next unless tag.types
+
             ::YARD::Tags::TypesExplainer::Parser.parse(tag.types.join(', ')).each do |types_explainer|
               check_mismatch_collection_type(comment, types_explainer)
             end
@@ -63,43 +67,33 @@ module RuboCop
               types_explainer.key_types.each { |t| check_mismatch_collection_type(comment, t) }
               types_explainer.value_types.each { |t| check_mismatch_collection_type(comment, t) }
             else
-              message = "`{KeyType => ValueType}` is the hash collection type syntax. #{did_you_mean_type(types_explainer.name)}"
+              did_you_mean = types_explainer.name == 'Array' ? 'Did you mean `<Type>` or `Array<Type>`' : ''
+              message = "`{KeyType => ValueType}` is the hash collection type syntax. #{did_you_mean}"
               add_offense(tag_range_for_comment(comment), message: message)
             end
           when ::YARD::Tags::TypesExplainer::FixedCollectionType
-            if types_explainer.name == 'Array'
-              types_explainer.types.each { |t| check_mismatch_collection_type(comment, t) }
-            else
-              message = "`(Type)` is the fixed collection type syntax. #{did_you_mean_type(types_explainer.name)}"
+            if types_explainer.name == 'Hash'
+              message = "`(Type)` is the fixed collection type syntax. Did you mean `{KeyType => ValueType}` or `Hash{KeyType => ValueType}`"
               add_offense(tag_range_for_comment(comment), message: message)
+            else
+              types_explainer.types.each { |t| check_mismatch_collection_type(comment, t) }
             end
           when ::YARD::Tags::TypesExplainer::CollectionType
-            if types_explainer.name == 'Array'
-              types_explainer.types.each { |t| check_mismatch_collection_type(comment, t) }
-            else
-              message = "`<Type>` is the collection type syntax. #{did_you_mean_type(types_explainer.name)}"
+            if types_explainer.name == 'Hash'
+              message = "`<Type>` is the collection type syntax. `{KeyType => ValueType}` or `Hash{KeyType => ValueType}` is more good"
               add_offense(tag_range_for_comment(comment), message: message)
+            else
+              types_explainer.types.each { |t| check_mismatch_collection_type(comment, t) }
             end
           end
         end
 
-        def did_you_mean_type(name)
-          case name
-          when 'Hash'
-            'Did you mean `{KeyType => ValueType}` or `Hash{KeyType => ValueType}`'
-          when 'Array'
-            'Did you mean `<Type>` or `Array<Type>`'
-          else
-            ''
-          end
-        end
-
         def inline_comment?(comment)
           !comment_line?(comment.source_range.source_line)
         end
 
         def include_yard_tag?(comment)
-          comment.source.match?(/@(?:param|return)\s+\[.*\]/)
+          comment.source.match?(/@(?:param|return|option|raise|yieldparam|yieldreturn)\s+\[.*\]/)
         end
 
         def tag_range_for_comment(comment)

data/lib/rubocop/cop/yard_cops.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 
 require 'yard'
-require_relative 'yard/tag_type_syntax'
+require_relative 'yard/tag_type'
+require_relative 'yard/mismatch_name'

data/lib/rubocop/yard/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module YARD
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/sig/rubocop/yard.rbs

@@ -5,7 +5,7 @@ module RuboCop
   end
   module Cop
     module YARD
-      class TagTypeSyntax
+      class TagType
         type t = YARD::Tags::TypesExplainer::Type
                | ::YARD::Tags::TypesExplainer::CollectionType
                | ::YARD::Tags::TypesExplainer::FixedCollectionType

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-yard
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - ksss
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-14 00:00:00.000000000 Z
+date: 2023-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -51,7 +51,8 @@ files:
 - README.md
 - config/default.yml
 - lib/rubocop-yard.rb
-- lib/rubocop/cop/yard/tag_type_syntax.rb
+- lib/rubocop/cop/yard/mismatch_name.rb
+- lib/rubocop/cop/yard/tag_type.rb
 - lib/rubocop/cop/yard_cops.rb
 - lib/rubocop/yard.rb
 - lib/rubocop/yard/inject.rb