Merge pull request #4 from ksss/meaningless-tag

Implement YARD/MeaninglessTag

Author: ksss

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:

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

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

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]

lib/rubocop/cop/yard/tag_type.rb

@@ -3,7 +3,7 @@
 module RuboCop
   module Cop
     module YARD
-      # @example
+      # @example tag type
       #   # bad
       #   # @param [Integer String]
       #

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'

smoke/meaningless_tag.json

@@ -0,0 +1,69 @@
+{
+  "metadata": {
+    "rubocop_version": "1.56.2",
+    "ruby_engine": "ruby",
+    "ruby_version": "3.2.2",
+    "ruby_patchlevel": "53",
+    "ruby_platform": "arm64-darwin22"
+  },
+  "files": [
+    {
+      "path": "smoke/meaningless_tag.rb",
+      "offenses": [
+        {
+          "severity": "convention",
+          "message": "`@param` is meaningless tag on module",
+          "cop_name": "YARD/MeaninglessTag",
+          "corrected": false,
+          "correctable": false,
+          "location": {
+            "start_line": 1,
+            "start_column": 1,
+            "last_line": 1,
+            "last_column": 19,
+            "length": 19,
+            "line": 1,
+            "column": 1
+          }
+        },
+        {
+          "severity": "convention",
+          "message": "`@option` is meaningless tag on class",
+          "cop_name": "YARD/MeaninglessTag",
+          "corrected": false,
+          "correctable": false,
+          "location": {
+            "start_line": 3,
+            "start_column": 3,
+            "last_line": 3,
+            "last_column": 19,
+            "length": 17,
+            "line": 3,
+            "column": 3
+          }
+        },
+        {
+          "severity": "convention",
+          "message": "`@option` is meaningless tag on casgn",
+          "cop_name": "YARD/MeaninglessTag",
+          "corrected": false,
+          "correctable": false,
+          "location": {
+            "start_line": 5,
+            "start_column": 5,
+            "last_line": 5,
+            "last_column": 21,
+            "length": 17,
+            "line": 5,
+            "column": 5
+          }
+        }
+      ]
+    }
+  ],
+  "summary": {
+    "offense_count": 3,
+    "target_file_count": 1,
+    "inspected_file_count": 1
+  }
+}

smoke/meaningless_tag.rb

@@ -0,0 +1,8 @@
+# @param [void] foo
+module Foo
+  # @option aaa bbb
+  class Bar
+    # @option ccc ddd
+    CONST = 1
+  end
+end