yard-lint 1.10.2 → 1.10.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1b9f3a39ce5fb15c2a1ace664e45d393fb70e429220085ebd4a7881aa2496cc
-  data.tar.gz: 207fb47ddd283bd62755c6f5736652166caed19a342f601ce78cfe73c0aad5e9
+  metadata.gz: b257fdb7ca6477899e3be3411289568fea84f44fbc3e06ae10e0803e236c4443
+  data.tar.gz: 44609a51c40daa3f6b9a0a85ea647448768d4ad34bbd4b99358effee51170f19
 SHA512:
-  metadata.gz: 7898934b15acdea1b39a244e6224969cef3848427b02db1711c87480ff8459b481920eb6a378fe25296bf0c2dc708d7f3b63ec7c8bd25effb7ea92d8c21179df
-  data.tar.gz: cb7525e59baebfe5cbb1e192ed91d38c6c75d04a4fd1ed9c60db1616794e66b67b46b39cefd5fa734565b30bb7bb4419fe672cbe798b2019443c0d5f59e7f7ae
+  metadata.gz: b4c98789f3b1bfab2c0cfa1fbdf69801adf0d7b942517fb99f7bb6c75ff3a95f050d7561a543b1d0b6e0ea749d6d63e18b0d6efa179c8d0f4e7d07637d825fed
+  data.tar.gz: 9bfe860758ef6de5770acfacc2e821661f883491f923d169c7fa32d942c6979f88d68df8f57fc284b461a0e5e5d7661c58200df9c1a3018d5f8a8d50e66149c2

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 1.10.3 (2026-08-05)
+- **[Feature]** Added `Tags/TagSeparator` (opt-in, disabled by default, severity `convention`) - a stricter sibling of `Tags/TagGroupSeparator`. Where `TagGroupSeparator` only inserts a blank line between different tag *groups* (and therefore can never separate two tags of the same type, such as sibling `@param` tags), `TagSeparator` requires a blank line between *every* pair of consecutive tags. Tags listed under the `Exempt` option may immediately follow the previous tag without a blank line - useful for `@option` tags, which document keys of a preceding `@param` hash and read best when clustered directly beneath it. `RequireAfterDescription` additionally requires a blank line between the description and the first tag.
+- **[Feature]** `Documentation/UndocumentedObjects` gained an `ExcludedObjects` option that matches the fully-qualified name of any object - class, module, method, or constant - via exact names or `/regex/` patterns anchored to the full path. This closes a gap where constants could never be excluded: `ExcludedMethods` matches only the trailing method name and deliberately ignores classes/modules/constants (so a pattern like `/cache/` cannot silently suppress a class such as `Memcached`), which left no way to skip a constant like `ATui::Input::KEY_A_Z` or to target a single object by its full path. `ExcludedObjects` (e.g. `'/^ATui::Input::KEY_/'`, `'MyApp::Config::DEFAULTS'`, or arity notation `'MyApp::Api#call/1'`) now handles those cases; `ExcludedMethods` behavior is unchanged (#299).
+- **[Feature]** `Documentation/BlankLineBeforeDefinition` gained an `IgnoredCommentPatterns` option: comment lines matching any configured pattern are not treated as documentation, so a blank line below them is no longer reported as a detached docstring. This resolves false positives on comments that are not docs - commented-out code in a constant block (`# KEY_F12 = ...` then a blank line then `KEY_C_A = ...`), `# FIXME` notes, or section separators - without the linter having to guess which comments are code. Each entry is a `/regex/` (matched as a regular expression) or a plain string (matched as a literal at word boundaries, so `api` does not match inside `rapid`); invalid regexes are skipped. Genuine detached prose docstrings are still reported. Defaults to empty, so existing behaviour is unchanged (#300).
+- **[Bugfix]** `Documentation/BlankLineBeforeDefinition` offenses now carry their validator name. The result builder overrode the shared offense construction but omitted the `validator` field, so the text output rendered the offense as `    : Blank line ...` with an empty validator slot, leaving no way to tell which validator to disable. The name (`Documentation/BlankLineBeforeDefinition`) is now populated like every other validator (#300).
+- **[Bugfix]** `Documentation/OrphanedDocComment` no longer flags a tagged doc comment above a class variable assignment (`@@name = ...`) as orphaned. YARD's `ClassVariableHandler` registers class variables as documentable code objects and attaches the preceding comment to them (a bare `@private`/`@api` tag included), so the comment is not dropped - it was only the validator's definition matcher that recognized constants (`FOO = ...`) but not class variables. Class variable assignments are now recognized as documentable, so `# @private`/`@@logger = ...` internal-marker pairs are left alone. Single instance-variable assignments (`@cached = ...`), which YARD does not document, are still reported.
+
 ## 1.10.2 (2026-07-24)
 - **[Bugfix]** `Semantic/AbstractMethods` no longer flags an `@abstract` method whose body is `fail NotImplementedError`. `fail` is a built-in alias of `raise` (`Kernel#fail`), so `fail NotImplementedError` is an identical abstract-method guard to `raise NotImplementedError`, but the `AllowedImplementations` patterns are written with `raise` and were matched literally. A leading `fail` keyword is now normalized to `raise` before matching, so both forms are recognized (and any custom `raise`-based `AllowedImplementations` pattern automatically covers its `fail` alias). Identifiers such as `failure` and non-leading `fail(...)` calls are left untouched.
 

data/README.md

@@ -228,9 +228,19 @@ Documentation/UndocumentedObjects:
   Description: 'Checks for classes, modules, and methods without documentation.'
   Enabled: true
   Severity: warning
+  # Exclude methods by their (unqualified) name, name/arity, or /regex/
   ExcludedMethods:
     - 'initialize/0'
     - '/^_/'
+  # Exclude any object (class, module, method, or constant) by its
+  # fully-qualified name, full-path name/arity, or a /regex/ matched against
+  # the full path. Use this to skip constants (ExcludedMethods never applies to
+  # them) or to target a single object without matching same-named objects
+  # elsewhere.
+  ExcludedObjects:
+    - 'MyApp::Config::DEFAULTS'    # exact fully-qualified constant
+    - '/^MyApp::Keys::KEY_/'       # every KEY_* constant under MyApp::Keys
+    - 'MyApp::Api#call/1'          # only MyApp::Api#call with exactly 1 param
   # Skip classes inheriting from these base classes (exact full-path match)
   AllowedParentClasses:
     - StandardError

data/lib/yard/lint/templates/default_config.yml

@@ -36,6 +36,13 @@ Documentation/UndocumentedObjects:
   ExcludedMethods:
     - 'initialize/0'  # Exclude parameter-less initialize
     - '/^_/'          # Exclude private methods (by convention)
+  # ExcludedObjects matches the fully-qualified name of ANY object (class,
+  # module, method, or constant). Unlike ExcludedMethods it can exclude
+  # constants and be matched against a full path (exact name, name/arity, or /regex/).
+  # ExcludedObjects:
+  #   - 'MyApp::Config::DEFAULTS'    # exact fully-qualified constant
+  #   - '/^MyApp::Keys::KEY_/'       # every KEY_* constant under MyApp::Keys
+  #   - 'MyApp::Api#call/1'          # only MyApp::Api#call with exactly 1 param
   # AllowedParentClasses:
   #   - StandardError           # Skip error subclasses
   #   - ApplicationRecord       # Skip Rails model subclasses
@@ -107,6 +114,13 @@ Documentation/BlankLineBeforeDefinition:
   EnabledPatterns:
     SingleBlankLine: true
     OrphanedDocs: true
+  # Comment lines matching any of these patterns are NOT treated as
+  # documentation, so a blank line below them is not reported as a detached
+  # docstring. Each entry is a /regex/ or a literal matched at word boundaries.
+  # Handy for commented-out code in constant blocks, FIXME notes, separators, etc.
+  # IgnoredCommentPatterns:
+  #   - '/\A#\s*\w[\w:]*\s*=/'   # commented-out assignments, e.g. "# KEY = 1"
+  #   - 'FIXME'                  # a comment with the word FIXME
 
 Documentation/LineLength:
   Description: 'Detects documentation comment lines that exceed the configured maximum length.'
@@ -346,6 +360,13 @@ Tags/TagGroupSeparator:
     yield: [yield, yieldparam, yieldreturn]
   RequireAfterDescription: false
 
+Tags/TagSeparator:
+  Description: 'Enforces a blank line between every consecutive YARD tag.'
+  Enabled: false  # Opt-in validator
+  Severity: convention
+  Exempt: []
+  RequireAfterDescription: false
+
 Tags/ForbiddenTags:
   Description: 'Detects forbidden tag and type combinations.'
   Enabled: false  # Opt-in validator

data/lib/yard/lint/templates/strict_config.yml

@@ -40,6 +40,13 @@ Documentation/UndocumentedObjects:
   ExcludedMethods:
     - 'initialize/0'  # Exclude parameter-less initialize
     - '/^_/'          # Exclude private methods (by convention)
+  # ExcludedObjects matches the fully-qualified name of ANY object (class,
+  # module, method, or constant). Unlike ExcludedMethods it can exclude
+  # constants and be matched against a full path (exact name, name/arity, or /regex/).
+  # ExcludedObjects:
+  #   - 'MyApp::Config::DEFAULTS'    # exact fully-qualified constant
+  #   - '/^MyApp::Keys::KEY_/'       # every KEY_* constant under MyApp::Keys
+  #   - 'MyApp::Api#call/1'          # only MyApp::Api#call with exactly 1 param
   # AllowedParentClasses:
   #   - StandardError           # Skip error subclasses
   #   - ApplicationRecord       # Skip Rails model subclasses
@@ -110,6 +117,13 @@ Documentation/BlankLineBeforeDefinition:
   EnabledPatterns:
     SingleBlankLine: true
     OrphanedDocs: true
+  # Comment lines matching any of these patterns are NOT treated as
+  # documentation, so a blank line below them is not reported as a detached
+  # docstring. Each entry is a /regex/ or a literal matched at word boundaries.
+  # Handy for commented-out code in constant blocks, FIXME notes, separators, etc.
+  # IgnoredCommentPatterns:
+  #   - '/\A#\s*\w[\w:]*\s*=/'   # commented-out assignments, e.g. "# KEY = 1"
+  #   - 'FIXME'                  # a comment with the word FIXME
 
 Documentation/LineLength:
   Description: 'Detects documentation comment lines that exceed the configured maximum length.'
@@ -344,6 +358,13 @@ Tags/TagGroupSeparator:
     yield: [yield, yieldparam, yieldreturn]
   RequireAfterDescription: false
 
+Tags/TagSeparator:
+  Description: 'Enforces a blank line between every consecutive YARD tag.'
+  Enabled: false  # Opt-in validator
+  Severity: error
+  Exempt: []
+  RequireAfterDescription: false
+
 Tags/ForbiddenTags:
   Description: 'Detects forbidden tag and type combinations.'
   Enabled: false  # Opt-in validator

data/lib/yard/lint/validators/base.rb

@@ -186,7 +186,7 @@ module Yard
             superclass_path = superclass.respond_to?(:path) ? superclass.path.to_s : superclass.to_s
             next false if superclass_path.empty?
             # Every Ruby class without an explicit parent implicitly inherits from Object,
-            # so matching it would exempt all classes — never the intent.
+            # so matching it would exempt all classes - never the intent.
             # BasicObject is the root of the hierarchy and is guarded for the same reason.
             next false if superclass_path == 'Object' || superclass_path == 'BasicObject'
 
@@ -199,10 +199,10 @@ module Yard
         # object without reporting an offense.
         #
         # Three pattern forms are supported (matching ExcludedMethods convention):
-        #   - Exact name:    'call'          — matches any arity
-        #   - Arity:         'initialize/1'  — matches only the given parameter count
+        #   - Exact name:    'call'          - matches any arity
+        #   - Arity:         'initialize/1'  - matches only the given parameter count
         #                                      (required + optional, excluding * and &)
-        #   - Regex:         '/^perform/'    — matches against the bare method name
+        #   - Regex:         '/^perform/'    - matches against the bare method name
         #
         # Invalid regex patterns are silently ignored. The empty regex '//' is always
         # rejected (it would match every method, making the option useless).

data/lib/yard/lint/validators/documentation/blank_line_before_definition/config.rb

@@ -15,7 +15,13 @@ module Yard
               'EnabledPatterns' => {
                 'SingleBlankLine' => true,
                 'OrphanedDocs' => true
-              }
+              },
+              # Comment lines matching any of these patterns are not treated as
+              # documentation, so a blank line below them is not reported as a
+              # detached docstring. Each entry is a `/regex/` or a literal matched
+              # at word boundaries. Useful for commented-out code, `# FIXME`
+              # notes, etc.
+              'IgnoredCommentPatterns' => []
             }.freeze
           end
         end

data/lib/yard/lint/validators/documentation/blank_line_before_definition/result.rb

@@ -30,6 +30,7 @@ module Yard
                   severity: severity,
                   type: self.class.offense_type,
                   name: computed_offense_name,
+                  validator: validator_name,
                   message: build_message(offense_data),
                   location: offense_data[:location] || offense_data[:file],
                   location_line: offense_data[:line] || offense_data[:location_line] || 0

data/lib/yard/lint/validators/documentation/blank_line_before_definition/validator.rb

@@ -136,7 +136,8 @@ module Yard
             end
 
             # Check if a comment line is not YARD documentation (magic comment,
-            # shebang, tool sigil/directive, or a bare `#` separator).
+            # shebang, tool sigil/directive, a bare `#` separator, or a line the
+            # user has excluded via `IgnoredCommentPatterns`).
             # @param line [String] stripped comment line
             # @return [Boolean] true if the line should not count as documentation
             def non_documentation_comment?(line)
@@ -144,7 +145,70 @@ module Yard
                 line.start_with?('#!') ||                          # shebang
                 line.match?(/\A#\s*(rubocop|standard):/i) ||       # linter directives
                 line.match?(/\A#\s*typed:/i) ||                    # Sorbet sigil
-                line.match?(/\A#+\s*\z/)                           # bare # separator
+                line.match?(/\A#+\s*\z/) ||                         # bare # separator
+                ignored_comment?(line)                             # user-configured exclusions
+            end
+
+            # Whether the comment line matches one of the user-configured
+            # `IgnoredCommentPatterns`. Such a line is not treated as
+            # documentation, so it never counts as a docstring detached from the
+            # definition below it. This lets a project silence the blank-line
+            # offense for comments that are not docs - commented-out code in a
+            # constant block, `# FIXME` notes, section separators - without the
+            # linter having to guess what is and is not code (see issue #300).
+            # @param line [String] stripped comment line
+            # @return [Boolean] true if the line matches an ignored pattern
+            def ignored_comment?(line)
+              ignored_comment_patterns.any? { |pattern| pattern.match?(line) }
+            end
+
+            # Compiled `IgnoredCommentPatterns` from configuration. Each entry is
+            # either a `/regex/` (compiled as a regular expression) or a plain
+            # string (matched as a whole word). Blank entries, the empty regex
+            # `//`, and invalid regexes are dropped (an empty regex would match
+            # every comment, making the option useless - consistent with the
+            # other pattern-list options). Memoized for the lifetime of the
+            # validator.
+            # @return [Array<Regexp>] compiled patterns
+            def ignored_comment_patterns
+              @ignored_comment_patterns ||=
+                Array(config_or_default('IgnoredCommentPatterns'))
+                .compact
+                .map { |pattern| pattern.to_s.strip }
+                .reject(&:empty?)
+                .reject { |pattern| pattern == '//' }
+                .filter_map { |pattern| compile_comment_pattern(pattern) }
+            end
+
+            # Compile a single `IgnoredCommentPatterns` entry into a Regexp.
+            # A `/.../` entry is a regular expression. Anything else is a literal
+            # matched at word boundaries, so a fragment like `api` does not match
+            # inside `rapid` (which would silently suppress a real docstring); use
+            # a `/regex/` entry for substring or case-insensitive matching. An
+            # invalid regex is skipped (returns nil) rather than raising; the empty
+            # regex `//` is filtered out before it reaches here.
+            # @param pattern [String] one configured pattern
+            # @return [Regexp, nil]
+            def compile_comment_pattern(pattern)
+              if (match = pattern.match(%r{\A/(.+)/\z}))
+                Regexp.new(match[1])
+              else
+                Regexp.new(word_bounded_literal(pattern))
+              end
+            rescue RegexpError
+              nil
+            end
+
+            # Escape a literal pattern and anchor it at word boundaries, but only
+            # on a side that ends in a word character so punctuation-only patterns
+            # (e.g. `...` section separators) still match.
+            # @param pattern [String] the literal pattern
+            # @return [String] escaped, boundary-anchored regex source
+            def word_bounded_literal(pattern)
+              escaped = Regexp.escape(pattern)
+              escaped = "\\b#{escaped}" if pattern.match?(/\A\w/)
+              escaped = "#{escaped}\\b" if pattern.match?(/\w\z/)
+              escaped
             end
 
             # Check if the given pattern is enabled in configuration

data/lib/yard/lint/validators/documentation/line_length/validator.rb

@@ -9,7 +9,7 @@ module Yard
           #
           # Uses YARD's `docstring.line_range` to locate the exact source lines belonging to
           # each docstring block. This handles block comments, wrapped tag descriptions, and
-          # macro expansion correctly — no arithmetic reconstruction needed.
+          # macro expansion correctly - no arithmetic reconstruction needed.
           class Validator < Validators::Base
             in_process visibility: :all
 

data/lib/yard/lint/validators/documentation/line_length.rb

@@ -11,7 +11,7 @@ module Yard
         # above a documentable Ruby construct). YARD's parsed docstring is used to
         # determine which lines belong to a docstring, avoiding fragile backwards-scanning.
         #
-        # Disabled by default — enable it and set MaxLength to taste.
+        # Disabled by default - enable it and set MaxLength to taste.
         #
         # @example Bad - line exceeds MaxLength (120)
         #   # This documentation line is too long and exceeds the configured maximum length.

data/lib/yard/lint/validators/documentation/orphaned_doc_comment/validator.rb

@@ -29,12 +29,18 @@ module Yard
             # Also matches define_method which YARD handles via a built-in dynamic handler.
             # `attr\b` is matched after the `attr_*` variants so the bare `attr :name` form
             # (handled by YARD's attribute handler) is recognised without swallowing them.
+            # Class variable assignments (`@@name = ...`) are matched too: YARD's
+            # ClassVariableHandler registers them as documentable objects and attaches the
+            # preceding comment (including a bare `@private`/`@api` tag), so such a comment is
+            # not orphaned.
             DEFINITION_PATTERN = /
               \A\s*(private\s+|protected\s+|public\s+)?
               (def |class |module |attr_reader|attr_writer|attr_accessor|attr_internal|attr\b|alias_method\b|alias\b|define_method\b)
               |
               \A\s*[A-Z][A-Za-z0-9_:]*\s*=
               |
+              \A\s*@@[A-Za-z_]\w*\s*=
+              |
               \A\s*\w+\s+def\b
             /x.freeze
 

data/lib/yard/lint/validators/documentation/text_substitution/parser.rb

@@ -22,7 +22,7 @@ module Yard
             def call(yard_output, **_kwargs)
               return [] if yard_output.nil? || yard_output.strip.empty?
 
-              # Do not strip lines — forbidden/replacement may have significant whitespace
+              # Do not strip lines - forbidden/replacement may have significant whitespace
               lines = yard_output.split("\n")
               violations = []
 

data/lib/yard/lint/validators/documentation/text_substitution.rb

@@ -8,17 +8,17 @@ module Yard
         #
         # Detects forbidden characters or strings in YARD documentation comments
         # and suggests replacements. The primary use case is detecting AI-generated
-        # em-dashes (—, U+2014) and en-dashes (–, U+2013) where a plain hyphen (-)
+        # em-dashes (-, U+2014) and en-dashes (-, U+2013) where a plain hyphen (-)
         # is preferred, but any string-to-string substitution rule can be configured.
         #
-        # All substitution rules are checked on every line — multiple violations can
+        # All substitution rules are checked on every line - multiple violations can
         # be reported for the same line when more than one forbidden string appears.
         # Fenced code blocks (``` ... ```) are skipped.
         #
-        # Disabled by default — enable it and configure Substitutions to taste.
+        # Disabled by default - enable it and configure Substitutions to taste.
         #
         # @example Bad - em-dash used in documentation
-        #   # Connects the start — and end of the range.
+        #   # Connects the start - and end of the range.
         #   def connect(start, finish)
         #   end
         #
@@ -39,8 +39,8 @@ module Yard
         #     Documentation/TextSubstitution:
         #       Enabled: true
         #       Substitutions:
-        #         "—": "-"    # em-dash (U+2014)
-        #         "–": "-"    # en-dash (U+2013)
+        #         "-": "-"    # em-dash (U+2014)
+        #         "-": "-"    # en-dash (U+2013)
         #         "…": "..."  # ellipsis (U+2026)
         #
         # To disable:

data/lib/yard/lint/validators/documentation/undocumented_objects/config.rb

@@ -12,6 +12,7 @@ module Yard
               'Enabled' => true,
               'Severity' => 'warning',
               'ExcludedMethods' => ['initialize/0'],
+              'ExcludedObjects' => [],
               'AllowedParentClasses' => []
             }.freeze
             self.combines_with = ['Documentation/UndocumentedBooleanMethods'].freeze

data/lib/yard/lint/validators/documentation/undocumented_objects/parser.rb

@@ -24,11 +24,15 @@ module Yard
                 'ExcludedMethods'
               ) || []
 
-              # Ensure excluded_methods is an Array
-              excluded_methods = Array(excluded_methods)
+              excluded_objects = config&.validator_config(
+                'Documentation/UndocumentedObjects',
+                'ExcludedObjects'
+              ) || []
 
-              # Sanitize patterns: remove nil, empty, whitespace-only, and normalize
-              excluded_methods = sanitize_patterns(excluded_methods)
+              # Ensure patterns are Arrays and sanitize: remove nil, empty,
+              # whitespace-only, and normalize
+              excluded_methods = sanitize_patterns(Array(excluded_methods))
+              excluded_objects = sanitize_patterns(Array(excluded_objects))
 
               yard_list_output
                 .split("\n")
@@ -41,6 +45,14 @@ module Yard
                   element = match[3]
                   arity = match[4]&.to_i
 
+                  # Skip if the fully-qualified object name is excluded. Unlike
+                  # ExcludedMethods (which matches only the trailing method name
+                  # and never applies to classes/modules/constants),
+                  # ExcludedObjects matches the whole element - so it can
+                  # exclude constants (e.g. "Foo::KEY_A") and lets a regex be
+                  # anchored to the full path.
+                  next if object_excluded?(element, arity, excluded_objects)
+
                   # Skip if method is in excluded list
                   next if method_excluded?(element, arity, excluded_methods)
 
@@ -88,6 +100,38 @@ module Yard
               end
             end
 
+            # Checks if an object should be excluded based on ExcludedObjects config.
+            # Matches against the fully-qualified object name (the whole element),
+            # so it applies to every object type - classes, modules, methods, and
+            # constants alike. Supports exact full names, arity notation (for
+            # methods), and regex patterns matched against the full path.
+            # @param element [String] the fully-qualified object name
+            #   (e.g. "Foo::Bar#baz", "Foo::Bar", "Foo::KEY_A")
+            # @param arity [Integer, nil] number of parameters for a method element
+            #   (required + optional, excluding splat and block); nil for
+            #   classes, modules, and constants
+            # @param excluded_objects [Array<String>] list of exclusion patterns
+            # @return [Boolean] true if the object should be excluded
+            def object_excluded?(element, arity, excluded_objects)
+              excluded_objects.any? do |pattern|
+                case pattern
+                when %r{^/(.+)/$}
+                  # Regex pattern matched against the full path: '/^Foo::KEY_/'
+                  match_regex_pattern(element, Regexp.last_match(1))
+                when %r{/\d+$}
+                  # Arity pattern on a full path: 'Foo::Bar#baz/1' matches the
+                  # method Foo::Bar#baz only when it takes exactly one parameter.
+                  # A full path contains a single '/' (the arity delimiter), so
+                  # match_arity_pattern splits it correctly. Constants and other
+                  # objects have a nil arity and never match an arity pattern.
+                  match_arity_pattern(element, arity, pattern)
+                else
+                  # Exact full-name match: 'Foo::Bar::KEY_A'
+                  element == pattern
+                end
+              end
+            end
+
             # Sanitize exclusion patterns
             # @param patterns [Array] raw patterns from config
             # @return [Array<String>] cleaned and validated patterns

data/lib/yard/lint/validators/documentation/undocumented_objects.rb

@@ -8,7 +8,35 @@ module Yard
         #
         # Checks for missing documentation on classes, modules, and methods.
         # This validator supports flexible method exclusions through the `ExcludedMethods`
-        # configuration option.
+        # configuration option, and full-object exclusions (including constants)
+        # through the `ExcludedObjects` option.
+        #
+        # ## `ExcludedMethods` vs `ExcludedObjects`
+        #
+        # `ExcludedMethods` matches only the **unqualified method name** (the part
+        # after the final `#`/`.`) and never applies to classes, modules, or
+        # constants. This keeps a pattern like `/cache/` from silently suppressing
+        # a class such as `Memcached`, but it means constants cannot be excluded and
+        # a method cannot be targeted by its full path.
+        #
+        # `ExcludedObjects` matches the **fully-qualified name** of any object -
+        # class, module, method, or constant - and supports exact names, arity
+        # notation (for methods), and regex patterns matched against the full path:
+        #
+        #     Documentation/UndocumentedObjects:
+        #       ExcludedObjects:
+        #         - 'MyApp::Config::DEFAULTS'   # exact fully-qualified constant
+        #         - '/^MyApp::Keys::KEY_/'      # every KEY_* constant under MyApp::Keys
+        #         - '/^MyApp::Internal#/'       # every method on MyApp::Internal
+        #         - 'MyApp::Api#call/1'         # only MyApp::Api#call with exactly 1 param
+        #
+        # Arity notation follows the same rules as `ExcludedMethods` (see below):
+        # the count is `required + optional` parameters, excluding splat (`*`) and
+        # block (`&`). Classes, modules, and constants have no arity and never match
+        # an arity pattern.
+        #
+        # Use `ExcludedObjects` when you need to skip constants (issue #299) or to
+        # exclude one specific object without affecting same-named objects elsewhere.
         #
         # ## Pattern Types
         #

data/lib/yard/lint/validators/tags/tag_separator/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagSeparator
+          # Configuration for TagSeparator validator
+          class Config < ::Yard::Lint::Validators::Config
+            self.id = :tag_separator
+            self.defaults = {
+              "Enabled" => false,
+              "Severity" => "convention",
+              "Exempt" => [],
+              "RequireAfterDescription" => false
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/tag_separator/messages_builder.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagSeparator
+          # Builds messages for missing tag separator offenses.
+          class MessagesBuilder
+            class << self
+              # Build message for missing tag separator.
+              #
+              # @param offense [Hash] offense data with :method_name and :separators keys
+              #
+              # @return [String] formatted message
+              def call(offense)
+                transitions = parse_transitions(offense[:separators])
+
+                if transitions.size == 1
+                  from, to = transitions.first
+                  "The `#{offense[:method_name]}` is missing a blank line between the " \
+                    "`#{from}` and `#{to}` tags."
+                else
+                  formatted = transitions.map { |from, to| "`#{from}` -> `#{to}`" }.join(", ")
+                  "The `#{offense[:method_name]}` is missing blank lines between tags: " \
+                    "#{formatted}."
+                end
+              end
+
+              private
+
+              # Parses transition string into array of [from, to] pairs.
+              #
+              # @param separators [String] string in format "from->to,from->to"
+              #
+              # @return [Array<Array<String>>] array of [from, to] pairs
+              def parse_transitions(separators)
+                separators
+                  .to_s
+                  .split(",")
+                  .map { |transition| transition.split("->") }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/tag_separator/parser.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagSeparator
+          # Parser for extracting tag separator violations from raw validator output.
+          #
+          # @example Output format (skip-lint)
+          #   /path/to/file.rb:10: ClassName#method_name
+          #   param->param,param->return
+          class Parser < Parsers::Base
+            # Parses raw validator output into structured offense data.
+            #
+            # @param raw_output [String] raw validator output string
+            #
+            # @return [Array<Hash>] array of hashes with offense details
+            def call(raw_output)
+              return [] if raw_output.nil? || raw_output.empty?
+
+              entries_by_location = {}
+
+              raw_output.split("\n").each_slice(2).each do |location, separators|
+                next if location.nil? || separators.nil?
+
+                # The location line is already a unique identifier for the
+                # documented object (file, line and title); using it directly
+                # as the key avoids collisions that a normalizing regexp could
+                # accidentally introduce between distinct paths/methods.
+                key = location.strip
+
+                if separators == "valid"
+                  entries_by_location[key] = "valid"
+                else
+                  entries_by_location[key] ||= [location, separators]
+                end
+              end
+
+              entries_by_location.delete_if { |_key, value| value == "valid" }
+
+              location_parser = Validators::Documentation::UndocumentedMethodArguments::Parser.new
+
+              # Parse each location together with its own separators so that an
+              # unparseable location line drops only its own offense instead of
+              # shifting the separators of all offenses that follow it
+              entries_by_location.values.filter_map do |location, separators|
+                offense = location_parser.call(location).first
+                next unless offense
+
+                offense[:separators] = separators
+                offense
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/tag_separator/result.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagSeparator
+          # Result object for tag separator validation.
+          # Transforms parsed separator violations into offense objects.
+          class Result < Results::Base
+            self.default_severity = "convention"
+            self.offense_type = "method"
+            self.offense_name = "MissingTagSeparator"
+
+            # Build human-readable message for tag separator offense.
+            #
+            # @param offense [Hash] offense data with :method_name and :separators keys
+            #
+            # @return [String] formatted message
+            def build_message(offense)
+              MessagesBuilder.call(offense)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/tag_separator/validator.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        module TagSeparator
+          # Validates that a blank line separates every pair of consecutive YARD tags.
+          #
+          # Unlike {TagGroupSeparator}, which only separates different tag groups,
+          # this validator requires a blank line between all consecutive tags,
+          # including same-type tags such as sibling @param tags. Tags listed in
+          # the Exempt option may immediately follow the previous tag.
+          class Validator < Base
+            # Enable in-process execution with all visibility
+            in_process visibility: :all
+
+            # Execute query for a single object during in-process execution.
+            # Checks if consecutive tags are separated by blank lines.
+            #
+            # @param object [YARD::CodeObjects::Base] the code object to query
+            # @param collector [Executor::ResultCollector] collector for output
+            #
+            # @return [void]
+            def in_process_query(object, collector)
+              # is_alias? exists only on method objects; on namespace objects
+              # YARD's method_missing raises NameError, so guard by type first
+              return if object.type == :method && object.is_alias?
+
+              docstring = object.docstring.all
+              return if docstring.nil? || docstring.empty?
+
+              transitions = offending_transitions(docstring)
+
+              collector.puts "#{object.file}:#{object.line}: #{object.title}"
+
+              if transitions.empty?
+                collector.puts "valid"
+              else
+                collector.puts transitions.map { |transition| "#{transition[:from]}->#{transition[:to]}" }.join(",")
+              end
+            end
+
+            private
+
+            # Find all locations where a blank line separator is missing between tags
+            #
+            # In YARD, a docstring's free-form description can only appear before the
+            # first `@tag`. Once the parser hits a tag, everything that follows
+            # (until the next tag) is considered part of that tag's content.
+            #
+            # A description is optional.
+            #
+            # A segment is a part of the docstring. It is either the free-form
+            # description or a YARD tag.
+            #
+            # The first segment never results in an offense.
+            #
+            # @param docstring [String] the raw docstring content
+            #
+            # @return [Array<Hash>] array of hashes with :from and :to tag names
+            def offending_transitions(docstring)
+              lines = docstring.split("\n")
+              transitions = []
+
+              previous_segment_name = nil # nil means we are processing the first segment
+
+              had_blank_line = true
+
+              lines.each do |line|
+                if line.strip.empty?
+                  had_blank_line = true
+                  next
+                end
+
+                # YARD tags begin at column 0 of the docstring. Indented @-leading
+                # lines are tag continuation or @example/code content (e.g. an
+                # instance variable like `@result`), not new tags.
+                tag_name = line[/\A@(\S+)/, 1]
+
+                if tag_name
+                  if offending_transition?(previous_segment_name, had_blank_line, tag_name)
+                    transitions << {from: previous_segment_name, to: tag_name}
+                  end
+
+                  previous_segment_name = tag_name
+                elsif previous_segment_name.nil?
+                  previous_segment_name = "description"
+                end
+
+                had_blank_line = false
+              end
+
+              transitions
+            end
+
+            # Whether a missing separator should be reported between the previous
+            # segment and the current tag
+            #
+            # @param previous_segment_name [String, nil] the previous tag name, 'description', or nil
+            # @param had_blank_line [Boolean] whether a blank line preceded the current tag
+            # @param tag_name [String] the current tag name
+            #
+            # @return [Boolean] whether to report a missing separator
+            def offending_transition?(previous_segment_name, had_blank_line, tag_name)
+              # The first segment never results in an offense
+              return false if previous_segment_name.nil?
+
+              # If a blank line occurs between the previous segment and the current
+              # tag there is no offense
+              return false if had_blank_line
+
+              # In a description->tag transition, exempt does not apply. This
+              # transition is only an offense if the RequireAfterDescription option
+              # is set.
+              return require_after_description? if previous_segment_name == "description"
+
+              return false if exempt.include?(tag_name)
+
+              true
+            end
+
+            # @return [Array<String>] tag names that may follow without a blank line
+            def exempt
+              @exempt ||= config.validator_config("Tags/TagSeparator", "Exempt") ||
+                Config.defaults["Exempt"]
+            end
+
+            # @return [Boolean] whether to require separator after description
+            def require_after_description?
+              @require_after_description ||= config.validator_config(
+                "Tags/TagSeparator",
+                "RequireAfterDescription"
+              ) || false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/validators/tags/tag_separator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    module Validators
+      module Tags
+        # TagSeparator validator
+        #
+        # Enforces a blank line between *every* pair of consecutive YARD tags,
+        # including consecutive tags of the same type (e.g. two `@param` tags).
+        # This is stricter than {TagGroupSeparator}, which only separates
+        # different tag *groups* and therefore can never separate same-type tags
+        # such as sibling `@param` tags. This validator is disabled by default.
+        #
+        # @example Bad - No blank line between consecutive @param tags
+        #   # @param organization_id [String] the organization ID
+        #   # @param id [String] the pet ID
+        #   # @return [Pet] the pet object
+        #   def call(organization_id, id)
+        #   end
+        #
+        # @example Good - Blank line separates every tag
+        #   # @param organization_id [String] the organization ID
+        #   #
+        #   # @param id [String] the pet ID
+        #   #
+        #   # @return [Pet] the pet object
+        #   def call(organization_id, id)
+        #   end
+        #
+        # ## Configuration
+        #
+        # To enable this validator:
+        #
+        #     Tags/TagSeparator:
+        #       Enabled: true
+        #
+        # To allow certain tags to immediately follow the previous tag without a
+        # blank line, list them under `Exempt`. This is useful for `@option`
+        # tags, which document keys of a preceding `@param` hash and read best
+        # when clustered directly beneath it:
+        #
+        #     Tags/TagSeparator:
+        #       Enabled: true
+        #       Exempt:
+        #         - option
+        #
+        # With the configuration above, this is valid:
+        #
+        #     # @param opts [Hash] the options
+        #     # @option opts [String] :name the name
+        #     # @option opts [Integer] :age the age
+        #     #
+        #     # @return [void]
+        #
+        # To also require a blank line between the description and the first tag,
+        # set `RequireAfterDescription`:
+        #
+        #     Tags/TagSeparator:
+        #       Enabled: true
+        #       RequireAfterDescription: true
+        module TagSeparator
+        end
+      end
+    end
+  end
+end

data/lib/yard/lint/version.rb

@@ -3,6 +3,6 @@
 module Yard
   module Lint
     # @return [String] version of the YARD Lint gem
-    VERSION = '1.10.2'
+    VERSION = '1.10.3'
   end
 end

data/lib/yard/lint.rb

@@ -25,7 +25,7 @@ module Yard
       #   - :mode [Symbol] one of :ref, :staged, :changed
       #   - :base_ref [String, nil] base ref for :ref mode (auto-detects main/master if nil)
       # @param source [String, nil] in-memory source content; when given, the file is not
-      #   read from disk — `path` must be a single .rb file path (used for config/exclusion
+      #   read from disk - `path` must be a single .rb file path (used for config/exclusion
       #   resolution and offense location reporting only)
       # @return [Yard::Lint::Result] result object with offenses
       def run(path:, config: nil, config_file: nil, progress: nil, diff: nil, source: nil)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yard-lint
 version: !ruby/object:Gem::Version
-  version: 1.10.2
+  version: 1.10.3
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -247,6 +247,12 @@ files:
 - lib/yard/lint/validators/tags/tag_group_separator/parser.rb
 - lib/yard/lint/validators/tags/tag_group_separator/result.rb
 - lib/yard/lint/validators/tags/tag_group_separator/validator.rb
+- lib/yard/lint/validators/tags/tag_separator.rb
+- lib/yard/lint/validators/tags/tag_separator/config.rb
+- lib/yard/lint/validators/tags/tag_separator/messages_builder.rb
+- lib/yard/lint/validators/tags/tag_separator/parser.rb
+- lib/yard/lint/validators/tags/tag_separator/result.rb
+- lib/yard/lint/validators/tags/tag_separator/validator.rb
 - lib/yard/lint/validators/tags/tag_type_position.rb
 - lib/yard/lint/validators/tags/tag_type_position/config.rb
 - lib/yard/lint/validators/tags/tag_type_position/messages_builder.rb
@@ -304,6 +310,8 @@ metadata:
   homepage_uri: https://github.com/mensfeld/yard-lint
   source_code_uri: https://github.com/mensfeld/yard-lint
   changelog_uri: https://github.com/mensfeld/yard-lint/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/mensfeld/yard-lint/issues
+  documentation_uri: https://github.com/mensfeld/yard-lint
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: