rubocop-yard 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b62c88ebfb27a008a19460e87ced5cde1352bd778fd7432052606b1220cd82aa
-  data.tar.gz: 11799a04ee4e9944c1303d5daedab3e09eca7ad01262c155ee9022689acb1d73
+  metadata.gz: 35f55b03315d73095819182351a19278528a8d91f5fb71f9644e39734ef0aa89
+  data.tar.gz: 731f21ea908307e87b59e36dae70fc9da5ced99157cdc53d0084c077673fd496
 SHA512:
-  metadata.gz: 4743f4c79a957b78f28af9639bd78fd06f37c935d52e9123e6a48d2c9280db8132153c2f0f299dba401d0df351858517d5a13b62d4d446042a0ef1419b6aa343
-  data.tar.gz: 5ea7b97be5355401201a0c50692dd9079211c42b5e99b19c4120d2873708e3a5b464747b75f5fa2e1822779169d3d762cd5c5339bade0bb54b6fef9ec6edb886
+  metadata.gz: 378e7d10ff7f50c807a1fe0fe6266e7163ebcece3bc6a4cf340cf98baade320a4785d2520c42aa9319bc20e20642dc46b39311088b58e521f57ee0ce15fab48b
+  data.tar.gz: a33bc93f4cb7712b0c73c259d3ecb7f94409973ec73c897494e723c33f5879b7686deba726e7a1f871da20aae3abd46554641c8d1ea29d5c58124cc66646213e

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.4.0] - 2023-09-19
+
+- Add new cop `YARD/MeaninglessTag`
+
 ## [0.3.1] - 2023-09-16
 
 Fix config/default.yml

data/README.md

@@ -12,12 +12,12 @@ Check tag type syntax error.
 
 ```
 # @param [Symbol|String]
-#         ^^^^^^^^^^^^^ SyntaxError as YARD tag type
+          ^^^^^^^^^^^^^ SyntaxError as YARD tag type
 ```
 
 ```
 # @param [Hash<Symbol, String>]
-#         ^^^^^^^^^^^^^^^^^^^^ `<Type>` is the collection type syntax. Did you mean `{KeyType => ValueType}` or `Hash{KeyType => ValueType}`
+          ^^^^^^^^^^^^^^^^^^^^ `<Type>` is the collection type syntax. Did you mean `{KeyType => ValueType}` or `Hash{KeyType => ValueType}`
 ```
 
 ### `YARD/MismatchName`
@@ -26,12 +26,25 @@ Check `@param` and `@option` name with method definition.
 
 ```rb
 # @param [String] string
-#                 ^^^^^^ `string` is not found in method arguments
+                  ^^^^^^ `string` is not found in method arguments
 # @option opt bar [String]
-#         ^^^ `opt` is not found in method arguments
+          ^^^ `opt` is not found in method arguments
 def foo(strings, opts = {})
 ```
 
+### `YARD/MeaninglessTag`
+
+Check `@param` and `@option` with class/module or casgn
+
+```rb
+# @param [String] foo
+^^^^^^^^^^^^^^^^^^^^^ `@param` is meaningless tag on module
+module Foo
+  # @option foo bar [String]
+  ^^^^^^^^^^^^^^^^^^^^^^^^^^ `@option` is meaningless tag on casgn
+  CONST = 1
+```
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/config/default.yml

@@ -1,3 +1,8 @@
+YARD/MeaninglessTag:
+  Description: 'Check meaningless tag'
+  Enabled: true
+  VersionAdded: '0.4.0'
+
 YARD/TagType:
   Description: 'Check syntax for yard tag type'
   Enabled: true

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module YARD
+      # @example meaningless tag
+      #   # bad
+      #   # @param [String] foo
+      #   # @option bar baz [String]
+      #   class Foo
+      #
+      #   # bad
+      #   # @param [String] foo
+      #   # @option bar baz [String]
+      #   CONST = 1
+      #
+      #   # good
+      #   class Foo
+      #
+      #   # good
+      #   CONST = 1
+      class MeaninglessTag < Base
+        include RangeHelp
+        include DocumentationComment
+
+        def on_class(node)
+          check(node)
+        end
+        alias on_module on_class
+        alias on_casgn on_class
+
+        def check(node)
+          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'
+
+            comment = preceding_lines.find { |line| line.text.include?("@#{tag.tag_name}") }
+            next unless comment
+
+            add_offense(comment, message: "`@#{tag.tag_name}` is meaningless tag on #{node.type}")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module YARD
-      # @example
+      # @example mismatch name
       #   # bad
       #   # @param [void] baz
       #   # @option opt aaa [void]
@@ -12,7 +12,7 @@ module RuboCop
       #
       #   # good
       #   # @param [void] bar
-      #   # @param [Array] argsa
+      #   # @param [Array] arg
       #   # @option opts aaa [void]
       #   def foo(bar, opts = {}, *arg)
       #   end

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

@@ -3,37 +3,36 @@
 module RuboCop
   module Cop
     module YARD
-      # @example
+      # @example tag type
       #   # bad
-      #   @param [Integer String]
+      #   # @param [Integer String]
       #
       #   # bad
-      #   @param [Hash<Symbol, String>]
+      #   # @param [Hash<Symbol, String>]
       #
       #   # bad
-      #   @param [Hash(String)]
+      #   # @param [Hash(String)]
       #
       #   # bad
-      #   @param [Array{Symbol => String}]
+      #   # @param [Array{Symbol => String}]
       #
       #   # good
-      #   @param [Integer, String]
+      #   # @param [Integer, String]
       #
       #   # good
-      #   @param [<String>]
-      #   @param [Array<String>]
-      #   @param [List<String>]
-      #   @param [Array<(String, Fixnum, Hash)>]
+      #   # @param [<String>]
+      #   # @param [Array<String>]
+      #   # @param [List<String>]
+      #   # @param [Array<(String, Fixnum, Hash)>]
       #
       #   # good
-      #   @param [(String)]
-      #   @param [Array(String)]
+      #   # @param [(String)]
+      #   # @param [Array(String)]
       #
       #   # good
-      #   @param [{KeyType => ValueType}]
-      #   @param [Hash{KeyType => ValueType}]
+      #   # @param [{KeyType => ValueType}]
+      #   # @param [Hash{KeyType => ValueType}]
       class TagType < Base
-        MSG = ''
         include RangeHelp # @return [void,]
 
         def on_new_investigation
@@ -50,13 +49,22 @@ module RuboCop
         def check(comment)
           docstring = comment.text.gsub(/\A#\s*/, '')
           ::YARD::DocstringParser.new.parse(docstring).tags.each do |tag|
-            next unless tag.types
+            types = extract_tag_type(tag)
 
-            ::YARD::Tags::TypesExplainer::Parser.parse(tag.types.join(', ')).each do |types_explainer|
-              check_mismatch_collection_type(comment, types_explainer)
+            check_syntax_error(comment) do
+              types_explainers = ::YARD::Tags::TypesExplainer::Parser.parse(types.join(', '))
+              types_explainers.each do |types_explainer|
+                check_mismatch_collection_type(comment, types_explainer)
+              end
             end
-          rescue SyntaxError
-            add_offense(tag_range_for_comment(comment), message: 'SyntaxError as YARD tag type')
+          end
+        end
+
+        def check_syntax_error(comment)
+          begin
+            yield
+          rescue SyntaxError => e
+            add_offense(tag_range_for_comment(comment), message: "(#{e.class}) #{e.message}")
           end
         end
 
@@ -88,12 +96,21 @@ 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
 
         def include_yard_tag?(comment)
-          comment.source.match?(/@(?:param|return|option|raise|yieldparam|yieldreturn)\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,5 +1,6 @@
 # frozen_string_literal: true
 
 require 'yard'
+require_relative 'yard/meaningless_tag'
 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.3.1"
+    VERSION = "0.4.0"
   end
 end

metadata

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