yard-lint 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43a01c4ffe524ad45bfac735365768a8afaacf812a894c511b7e8d42c475e646
-  data.tar.gz: a10ebddfaacdeb54db032121df28c73efc82fae79898fce5b080491e4087c26d
+  metadata.gz: 312a8649c021c9df03d03240a80da73a5985b692f784bbe1143cf6f7138dbb78
+  data.tar.gz: ba230c3af103171163396ccc31ac2b4b8fb400b98faba25705072558ee9b71bb
 SHA512:
-  metadata.gz: 00b26fb9a801b71dc13c0e1050f1ecd6db7ce7e777ecfdf1e4916bedbfb63af273186c7a1327a24f371b6e02c18bcd5c51ae8b6fa24e4f0c63f64370021a7418
-  data.tar.gz: d7665d29d69631b17d4bfc82e77a08494131490167d9e2124e3b2b625f82ce8c263111448e8a66e0f95d1e87ef976e643480adfbaf915c962251161db0d99f71
+  metadata.gz: d14c94827a3b20f08c283aff9e60f82473dd91522e35f434012cf7b90bd23f7aeaaa3e4f95788d3e7fd32870ac96ee75c953b2bf176c4f38cc44ef9d0cb2e874
+  data.tar.gz: b8d9bdf4583ea0553b8badd02266d03b402a50926f26492ba1d5c956ee275d2e9fab97bcc773e9d7d160acae76e10746a8103937fa5ea01aeb46e0480fd0a0e2

data/CHANGELOG.md

@@ -1,4 +1,39 @@
-# Changelog
+# YARD-Lint Changelog
+
+## 1.0.0 (2025-11-09)
+- [Fix] Fix "Argument list too long" error on large codebases by using xargs pattern with temporary file lists
+- [Enhancement] Expand default exclusion patterns to include typical Ruby/Rails directories (test/, log/, coverage/, db/migrate/, etc.)
+- **[Feature]** Add `Tags/TypeSyntax` validator to detect malformed YARD type syntax using YARD's built-in parser
+  - Detects unclosed brackets: `Array<`, `Hash{Symbol =>`
+  - Detects empty generics: `Array<>`
+  - Detects malformed hash syntax: `Hash{Symbol}`
+  - Configurable `ValidatedTags` option (default: param, option, return, yieldreturn)
+- **[Feature]** Add `Tags/MeaninglessTag` validator to detect `@param` and `@option` tags on non-method objects
+  - Prevents meaningless tags on classes, modules, and constants
+  - Configurable `CheckedTags` (default: param, option) and `InvalidObjectTypes` (default: class, module, constant)
+- **[Feature]** Add `Tags/CollectionType` validator to enforce YARD's Hash collection syntax
+  - Enforces `Hash{K => V}` over `Hash<K, V>` (generic syntax from other languages)
+  - Configurable `ValidatedTags` (default: param, option, return, yieldreturn)
+  - Provides automatic correction suggestions
+- **[Feature]** Add `Tags/TagTypePosition` validator to validate type annotation position in tags
+  - Configurable style: `type_after_name` (YARD standard: `@param name [Type]`) or `type_first` (`@param [Type] name`)
+  - Only validates `@param` and `@option` tags (excludes `@return` as it has no parameter name)
+  - Reads source code directly to avoid false positives from YARD's internal docstring normalization
+- [Fix] Fix `Warnings/UnknownParameterName` validator showing only line number instead of full file path by correcting regex pattern
+- [Enhancement] Add comprehensive integration tests for `UnknownParameterName` validator
+- [Documentation] Add inline documentation explaining cache clearing in bin/yard-lint
+- [Documentation] Expand README with troubleshooting section for ExcludedMethods patterns
+
+## 0.2.2 (2025-11-07)
+- **[Feature]** Add `ExcludedMethods` configuration option to exclude methods from validation using simple names, regex patterns, or arity notation (default excludes parameter-less `initialize/0` methods).
+- [Fix] Fix `UndocumentedObjects` validator incorrectly flagging methods with `@return [Boolean]` tags as undocumented by using `docstring.all.empty?` instead of `docstring.blank?`.
+- [Fix] Fix `UndocumentedBooleanMethods` validator incorrectly flagging methods with `@return [Boolean]` (type without description text) by checking for return types instead of description text.
+- [Enhancement] Implement per-arguments YARD database isolation using SHA256 hash of arguments to prevent contamination between validators with different file selections.
+- [Refactoring] Remove file filtering workaround as database isolation eliminates the need for it.
+- [Change] YARD database directories are now created under a base temp directory with unique subdirectories per argument set.
+
+## 0.2.1 (2025-11-07)
+- Release to validate Trusted Publishing flow. 
 
 ## 0.2.0 (2025-11-07)
 

data/README.md

@@ -1,3 +1,8 @@
+![yard-lint logo](https://raw.githubusercontent.com/mensfeld/yard-lint/master/misc/logo.png)
+
+[![Build Status](https://github.com/mensfeld/yard-lint/actions/workflows/ci.yml/badge.svg)](https://github.com/mensfeld/yard-lint/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/yard-lint.svg)](http://badge.fury.io/rb/yard-lint)
+
 # YARD-Lint
 
 A comprehensive linter for YARD documentation that helps you maintain clean, consistent, and complete documentation in your Ruby and Ruby on Rails projects.
@@ -17,7 +22,11 @@ YARD-Lint validates your YARD documentation for:
 - **Undocumented code**: Classes, modules, methods, and constants without documentation
 - **Missing parameter documentation**: Methods with undocumented parameters
 - **Invalid tag types**: Type definitions that aren't valid Ruby classes or allowed defaults
+- **Invalid type syntax**: Malformed YARD type syntax (unclosed brackets, empty generics, etc.)
 - **Invalid tag ordering**: Tags that don't follow your specified order
+- **Meaningless tags**: `@param` or `@option` tags on classes, modules, or constants (only valid on methods)
+- **Collection type syntax**: Enforces `Hash{K => V}` over `Hash<K, V>` (YARD standard)
+- **Type annotation position**: Validates whether types appear before or after parameter names (configurable)
 - **Boolean method documentation**: Question mark methods missing return type documentation
 - **API tag validation**: Enforce @api tags on public objects and validate API values
 - **Abstract method validation**: Ensure @abstract methods don't have real implementations
@@ -96,6 +105,14 @@ Documentation/UndocumentedObjects:
   Description: 'Checks for classes, modules, and methods without documentation.'
   Enabled: true
   Severity: warning
+  # List of methods to exclude from validation
+  # Supports three patterns:
+  #   - Exact names: 'method_name' (excludes all methods with this name)
+  #   - Arity notation: 'method_name/N' (excludes only if method has N parameters)
+  #   - Regex patterns: '/pattern/' (excludes methods matching the regex)
+  ExcludedMethods:
+    - 'initialize/0'  # Exclude only parameter-less initialize (default)
+    - '/^_/'          # Exclude private methods (by convention)
 
 Documentation/UndocumentedMethodArguments:
   Description: 'Checks for method parameters without @param tags.'
@@ -130,6 +147,49 @@ Tags/InvalidTypes:
     - CustomType
     - MyType
 
+Tags/TypeSyntax:
+  Description: 'Validates YARD type syntax using YARD parser.'
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/MeaninglessTag:
+  Description: 'Detects @param/@option tags on classes, modules, or constants.'
+  Enabled: true
+  Severity: warning
+  CheckedTags:
+    - param
+    - option
+  InvalidObjectTypes:
+    - class
+    - module
+    - constant
+
+Tags/CollectionType:
+  Description: 'Validates Hash collection syntax (enforces Hash{K => V} over Hash<K, V>).'
+  Enabled: true
+  Severity: convention
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/TagTypePosition:
+  Description: 'Validates type annotation position in tags.'
+  Enabled: true
+  Severity: convention
+  CheckedTags:
+    - param
+    - option
+  # EnforcedStyle: 'type_after_name' (YARD standard: @param name [Type])
+  #                or 'type_first' (@param [Type] name)
+  EnforcedStyle: type_after_name
+
 Tags/ApiTags:
   Description: 'Enforces @api tags on public objects.'
   Enabled: false  # Opt-in validator
@@ -297,12 +357,16 @@ Supported glob patterns:
 | Validator | Description | Default | Configuration Options |
 |-----------|-------------|---------|----------------------|
 | **Documentation Validators** |
-| `Documentation/UndocumentedObjects` | Checks for classes, modules, and methods without documentation | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
+| `Documentation/UndocumentedObjects` | Checks for classes, modules, and methods without documentation | Enabled (warning) | `Enabled`, `Severity`, `Exclude`, `ExcludedMethods` |
 | `Documentation/UndocumentedMethodArguments` | Checks for method parameters without `@param` tags | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
 | `Documentation/UndocumentedBooleanMethods` | Checks that question mark methods document their boolean return | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
 | **Tags Validators** |
 | `Tags/Order` | Enforces consistent ordering of YARD tags | Enabled (convention) | `Enabled`, `Severity`, `Exclude`, `EnforcedOrder` |
 | `Tags/InvalidTypes` | Validates type definitions in `@param`, `@return`, `@option` tags | Enabled (warning) | `Enabled`, `Severity`, `Exclude`, `ValidatedTags`, `ExtraTypes` |
+| `Tags/TypeSyntax` | Validates YARD type syntax (detects unclosed brackets, empty generics, etc.) | Enabled (warning) | `Enabled`, `Severity`, `Exclude`, `ValidatedTags` |
+| `Tags/MeaninglessTag` | Detects `@param`/`@option` tags on classes, modules, or constants (only valid on methods) | Enabled (warning) | `Enabled`, `Severity`, `Exclude`, `CheckedTags`, `InvalidObjectTypes` |
+| `Tags/CollectionType` | Enforces `Hash{K => V}` over `Hash<K, V>` (YARD standard collection syntax) | Enabled (convention) | `Enabled`, `Severity`, `Exclude`, `ValidatedTags` |
+| `Tags/TagTypePosition` | Validates type annotation position (`@param name [Type]` vs `@param [Type] name`) | Enabled (convention) | `Enabled`, `Severity`, `Exclude`, `CheckedTags`, `EnforcedStyle` |
 | `Tags/ApiTags` | Enforces `@api` tags on public objects | Disabled (opt-in) | `Enabled`, `Severity`, `Exclude`, `AllowedApis` |
 | `Tags/OptionTags` | Requires `@option` tags for methods with options parameters | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
 | **Warnings Validators** |
@@ -315,6 +379,118 @@ Supported glob patterns:
 | **Semantic Validators** |
 | `Semantic/AbstractMethods` | Ensures `@abstract` methods don't have real implementations | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
 
+### Excluding Methods from Documentation Validation
+
+The `Documentation/UndocumentedObjects` validator supports a flexible `ExcludedMethods` configuration option that allows you to exclude specific methods from documentation requirements. This supports three pattern types:
+
+#### Pattern Types
+
+1. **Exact Name Matching**
+   ```yaml
+   ExcludedMethods:
+     - 'to_s'           # Excludes ALL to_s methods regardless of parameters
+     - 'inspect'        # Excludes ALL inspect methods
+   ```
+   Note: Exact name matching excludes the method with **any arity**. If you need arity-specific exclusions, use arity notation instead.
+
+2. **Arity Notation** (method_name/N)
+   ```yaml
+   ExcludedMethods:
+     - 'initialize/0'   # Only excludes initialize with NO parameters (default)
+     - 'call/1'         # Only excludes call methods with exactly 1 parameter
+     - 'initialize/2'   # Only excludes initialize with exactly 2 parameters
+   ```
+   Note: Arity counts total parameters (required + optional) excluding splat (*) and block (&) parameters.
+
+3. **Regex Patterns**
+   ```yaml
+   ExcludedMethods:
+     - '/^_/'           # Excludes all methods starting with underscore (private convention)
+     - '/^test_/'       # Excludes all test methods
+     - '/_(helper|util)$/' # Excludes methods ending with _helper or _util
+   ```
+
+#### Examples
+
+```yaml
+# Minimal setup: only exclude parameter-less initialize
+Documentation/UndocumentedObjects:
+  ExcludedMethods:
+    - 'initialize/0'
+
+# Common Rails/Ruby patterns
+Documentation/UndocumentedObjects:
+  ExcludedMethods:
+    - 'initialize/0'       # Parameter-less constructors
+    - '/^_/'               # Private methods (by convention)
+    - 'to_s'               # String conversion
+    - 'inspect'            # Object inspection
+    - 'hash'               # Hash code generation
+    - 'eql?'               # Equality comparison
+    - '=='                 # Binary equality operator
+    - '<=>'                # Spaceship operator (comparison)
+    - '+'                  # Addition operator
+    - '-'                  # Subtraction operator
+    - '+@'                 # Unary plus operator
+    - '-@'                 # Unary minus operator
+
+# Test framework exclusions
+Documentation/UndocumentedObjects:
+  ExcludedMethods:
+    - '/^test_/'           # Minitest methods
+    - '/^should_/'         # Shoulda methods
+    - 'setup/0'            # Setup with no params
+    - 'teardown/0'         # Teardown with no params
+```
+
+#### Pattern Validation & Edge Cases
+
+The `ExcludedMethods` feature includes robust validation and error handling:
+
+**Automatic Pattern Sanitization:**
+- **Nil values** are automatically removed
+- **Empty strings** and whitespace-only patterns are filtered out
+- **Whitespace trimming** is applied to all patterns
+- **Empty regex patterns** (`//`) are rejected (would match everything)
+- **Non-array values** are automatically converted to arrays
+
+**Invalid Pattern Handling:**
+- **Invalid regex patterns** (e.g., `/[/`, `/(unclosed`) are silently skipped without crashing
+- **Invalid arity notation** (e.g., `method/abc`, `method/`) is silently skipped
+- **Pattern matching is case-sensitive** for both exact names and regex
+
+**Operator Method Support:**
+YARD-Lint fully supports Ruby operator methods including:
+- Binary operators: `+`, `-`, `*`, `/`, `%`, `**`, `==`, `!=`, `===`, `<`, `>`, `<=`, `>=`, `<=>`, `&`, `|`, `^`, `<<`, `>>`
+- Unary operators: `+@`, `-@`, `!`, `~`
+- Other special methods: `[]`, `[]=`, `=~`
+
+**Pattern Matching Behavior:**
+- **Any match excludes**: If a method matches any pattern, it is excluded from validation
+- **Patterns are evaluated in order** as defined in the configuration
+- **Exact names have no arity restriction**: `'initialize'` excludes all initialize methods, regardless of parameters
+- **Arity notation is strict**: `'initialize/0'` only excludes initialize with exactly 0 parameters
+
+#### Troubleshooting ExcludedMethods
+
+**Methods still showing as undocumented:**
+1. Verify the method name matches exactly (case-sensitive)
+2. Check if you're using arity notation - ensure the arity count is correct
+3. For regex patterns, test your regex independently to ensure it matches
+4. Remember: Arity counts `required + optional` parameters, **excluding** splat (`*args`) and block (`&block`)
+
+**Regex patterns not working:**
+1. Ensure you're using `/pattern/` format with forward slashes
+2. Test the regex in Ruby: `Regexp.new('your_pattern').match?('method_name')`
+3. Escape special regex characters: `\.`, `\(`, `\)`, `\[`, `\]`, etc.
+4. Invalid regex patterns are silently skipped - check for syntax errors
+
+**Arity not matching:**
+1. Count parameters correctly: `def method(a, b = 1)` has arity 2 (required + optional)
+2. Splat parameters don't count: `def method(a, *rest)` has arity 1
+3. Block parameters don't count: `def method(a, &block)` has arity 1
+4. Keyword arguments count as individual parameters: `def method(a:, b:)` has arity 2
+
 ### Global Configuration
 
 | Option | Description | Default | Type |
@@ -449,6 +625,85 @@ def configure(name, options = {})
 end
 ```
 
+### Meaningless tag validation (enabled by default)
+
+This validator prevents `@param` and `@option` tags from being used on classes, modules, or constants, where they make no sense (these tags are only valid on methods).
+
+```ruby
+# Bad - @param on a class
+# @param name [String] this makes no sense on a class
+class User
+end
+
+# Bad - @option on a module
+# @option config [Boolean] :enabled modules don't have parameters
+module Authentication
+end
+
+# Good - @param on a method
+class User
+  # @param name [String] the user's name
+  def initialize(name)
+    @name = name
+  end
+end
+```
+
+To disable this validator:
+
+```yaml
+Tags/MeaninglessTag:
+  Enabled: false
+```
+
+### Collection type syntax validation (enabled by default)
+
+YARD uses `Hash{K => V}` syntax for hashes, not `Hash<K, V>` (which is generic syntax from other languages). This validator enforces the correct YARD syntax.
+
+```ruby
+# Bad - using generic syntax
+# @param options [Hash<Symbol, String>] configuration
+def configure(options)
+end
+
+# Good - using YARD syntax
+# @param options [Hash{Symbol => String}] configuration
+def configure(options)
+end
+
+# Also good - Array uses angle brackets
+# @param items [Array<String>] list of items
+def process(items)
+end
+```
+
+To disable this validator:
+
+```yaml
+Tags/CollectionType:
+  Enabled: false
+```
+
+### Type annotation position validation (enabled by default)
+
+This validator ensures consistent type annotation positioning. By default, it enforces YARD standard (`@param name [Type]`), but you can configure it to enforce `type_first` style if your team prefers it.
+
+```ruby
+# Good - type after parameter name (YARD standard)
+# @param name [String] the user's name
+# @param age [Integer] the user's age
+def create_user(name, age)
+end
+
+# Bad - type before parameter name
+# @param [String] name the user's name
+# @param [Integer] age the user's age
+def create_user(name, age)
+end
+```
+
+To use `type_first` style instead, set `EnforcedStyle: type_first` in your `.yard-lint.yml`.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'bundler/gem_tasks'

data/bin/yard-lint

@@ -52,6 +52,30 @@ unless path
   exit 1
 end
 
+# Clear YARD database and command cache to ensure fresh run on each CLI invocation
+#
+# Why this is necessary:
+#
+# 1. **Command Cache Reset** (`reset_command_cache!`)
+#    - The command cache stores results from YARD commands across validator instances
+#    - This cache is shared at the class level (Base.@shared_command_cache)
+#    - Without reset: Results from a previous CLI run could leak into the current run
+#    - Critical for CLI: Each `yard-lint` invocation should start with clean state
+#    - Not needed in-process: Within a single run, caching YARD results is beneficial
+#
+# 2. **YARD Database Clear** (`clear_yard_database!`)
+#    - YARD creates temp database directories for parsing documentation
+#    - Directories are isolated per-argument-set using SHA256 hash (see base.rb:84-97)
+#    - Base temp dir (YARDOC_BASE_TEMP_DIR) persists across CLI invocations
+#    - Without clear: Old databases accumulate in /tmp, wasting disk space
+#    - Database isolation prevents contamination within a single run, but doesn't
+#      clean up between runs
+#
+# In summary: These ensure each CLI invocation is independent and doesn't leak state
+# from previous runs, while also preventing temp directory accumulation.
+Yard::Lint::Validators::Base.reset_command_cache!
+Yard::Lint::Validators::Base.clear_yard_database!
+
 # Run the linter with config_file (it will be loaded internally)
 result = Yard::Lint.run(
   path: path,

data/lib/yard/lint/config.rb

@@ -86,7 +86,41 @@ module Yard
       # Global file exclusion patterns
       # @return [Array<String>] exclusion patterns
       def exclude
-        all_validators['Exclude'] || ['\.git', 'vendor/**/*', 'node_modules/**/*']
+        all_validators['Exclude'] || default_exclusions
+      end
+
+      # Default exclusion patterns for typical Ruby/Rails projects
+      # @return [Array<String>] default exclusion patterns
+      def default_exclusions
+        [
+          # Version control
+          '\.git',
+          # Dependencies
+          'vendor/**/*',
+          'node_modules/**/*',
+          # Test directories
+          'spec/**/*',
+          'test/**/*',
+          'features/**/*',
+          # Temporary and cache directories
+          'tmp/**/*',
+          'log/**/*',
+          'coverage/**/*',
+          '.bundle/**/*',
+          # Rails-specific
+          'db/schema.rb',
+          'db/migrate/**/*',
+          'public/assets/**/*',
+          'public/packs/**/*',
+          'public/system/**/*',
+          # Build artifacts
+          'pkg/**/*',
+          'doc/**/*',
+          '.yardoc/**/*',
+          # Configuration that doesn't need docs
+          'config/initializers/**/*',
+          'config/environments/**/*'
+        ]
       end
 
       # Minimum severity level to fail on

data/lib/yard/lint/config_loader.rb

@@ -37,7 +37,7 @@ module Yard
         # Auto-discover validators from the codebase
         # Scans the validators directory and loads all validator modules that have
         # an .id method and .defaults method (indicating they're valid validators)
-        # @return [Hash<String, Array<String>>] hash of category names to validator names
+        # @return [Hash{String => Array<String>}] hash of category names to validator names
         def discover_validators
           categories = Hash.new { |h, k| h[k] = [] }
 

data/lib/yard/lint/result_builder.rb

@@ -109,7 +109,16 @@ module Yard
         return [] unless stdout
 
         parsers = discover_parsers(validator_module)
-        parsers.flat_map { |parser| parser.new.call(stdout) }
+        parsers.flat_map do |parser|
+          parser_instance = parser.new
+          # Try passing config to parser if it accepts it (for filtering)
+          # Otherwise, call without config for backwards compatibility
+          begin
+            parser_instance.call(stdout, config: config)
+          rescue ArgumentError
+            parser_instance.call(stdout)
+          end
+        end
       end
 
       # Auto-discover parser classes in a validator module

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

@@ -17,12 +17,11 @@ module Yard
           '--no-progress'
         ].freeze
 
-        # String with a temp dir to store the YARD database
-        # @note We run YARD multiple times and in order not to rebuild db over and over
-        #   again but reuse the same one, we have a single tmp dir for it
-        YARDOC_TEMP_DIR = Dir.mktmpdir.freeze
+        # Base temp directory for YARD databases
+        # Each unique set of arguments gets its own subdirectory to prevent contamination
+        YARDOC_BASE_TEMP_DIR = Dir.mktmpdir.freeze
 
-        private_constant :YARDOC_TEMP_DIR
+        private_constant :YARDOC_BASE_TEMP_DIR
 
         attr_reader :config, :selection
 
@@ -42,12 +41,12 @@ module Yard
             Base.instance_variable_set(:@shared_command_cache, nil)
           end
 
-          # Clear the YARD database (primarily for testing)
+          # Clear all YARD databases (primarily for testing)
           # @return [void]
           def clear_yard_database!
-            return unless defined?(YARDOC_TEMP_DIR)
+            return unless defined?(YARDOC_BASE_TEMP_DIR)
 
-            FileUtils.rm_rf(Dir.glob(File.join(YARDOC_TEMP_DIR, '*')))
+            FileUtils.rm_rf(Dir.glob(File.join(YARDOC_BASE_TEMP_DIR, '*')))
           end
         end
 
@@ -66,21 +65,51 @@ module Yard
           return raw if selection.nil? || selection.empty?
 
           # Anything that goes to shell needs to be escaped
-          escaped_file_names = escape(selection).join(' ')
+          escaped_file_names = escape(selection)
 
-          yard_cmd(YARDOC_TEMP_DIR, escaped_file_names)
+          # Use a unique YARD database per set of arguments to prevent contamination
+          # between validators with different file selections or options
+          yardoc_dir = yardoc_temp_dir_for_arguments(escaped_file_names.join(' '))
+
+          # For large file lists, use a temporary file to avoid ARG_MAX limits
+          # Write file paths to temp file, one per line
+          Tempfile.create(['yard_files', '.txt']) do |f|
+            escaped_file_names.each { |file| f.puts(file) }
+            f.flush
+
+            yard_cmd(yardoc_dir, f.path)
+          end
         end
 
         private
 
+        # Returns a unique YARD database directory for the given arguments
+        # Uses SHA256 hash of the normalized arguments to ensure different file sets
+        # get separate databases, preventing contamination
+        # @param escaped_file_names [String] escaped file names to process
+        # @return [String] path to the YARD database directory
+        def yardoc_temp_dir_for_arguments(escaped_file_names)
+          # Combine all arguments that affect YARD output
+          all_args = "#{shell_arguments} #{escaped_file_names}"
+
+          # Create a hash of the arguments for a unique directory name
+          args_hash = Digest::SHA256.hexdigest(all_args)
+
+          # Create subdirectory under base temp dir
+          dir = File.join(YARDOC_BASE_TEMP_DIR, args_hash)
+          FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+          dir
+        end
+
         # @return [String] all arguments with which YARD command should be executed
         def shell_arguments
-          validator_name = self.class.name.split('::').then do |parts|
+          validator_name = self.class.name&.split('::')&.then do |parts|
             idx = parts.index('Validators')
             next config.options unless idx && parts[idx + 1] && parts[idx + 2]
 
             "#{parts[idx + 1]}/#{parts[idx + 2]}"
-          end
+          end || config.options
 
           yard_options = config.validator_yard_options(validator_name)
           args = escape(yard_options).join(' ')

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

@@ -9,13 +9,15 @@ module Yard
           # do not have a return type or return description documented
           class Validator < Base
             # Query to find all the boolean methods without proper return documentation
+            # Requires either: no @return tag, OR @return tag with no types specified
+            # Accepts @return [Boolean] without description text as valid documentation
             QUERY = <<~QUERY.tr("\n", ' ')
               '
                 type == :method &&
                 !is_alias? &&
                 is_explicit? &&
                 name.to_s.end_with?("?") &&
-                (tag("return").nil? || tag("return").text.to_s.strip.empty?)
+                (tag("return").nil? || tag("return").types.to_a.empty?)
               '
             QUERY
 
@@ -25,16 +27,15 @@ module Yard
 
             # Runs yard list query with proper settings on a given dir and files
             # @param dir [String] dir where we should generate the temp docs
-            # @param escaped_file_names [String] files for which we want to get the stats
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
             # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               cmd = <<~CMD
-                yard list \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard list \
                   #{shell_arguments} \
                 --query #{QUERY} \
                 -q \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
 

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

@@ -29,19 +29,18 @@ module Yard
 
             # Runs yard list query with proper settings on a given dir and files
             # @param dir [String] dir where we should generate the temp docs
-            # @param escaped_file_names [String] files for which we want to get the stats
+            # @param file_list_path [String] path to temp file containing file paths (one per line)
             # @return [Hash] shell command execution hash results
-            def yard_cmd(dir, escaped_file_names)
+            def yard_cmd(dir, file_list_path)
               shell_args = shell_arguments
               UNWANTED_OPTIONS.each { |opt| shell_args.gsub!(opt, '') }
 
               cmd = <<~CMD
-                yard list \
+                cat #{Shellwords.escape(file_list_path)} | xargs yard list \
                   #{shell_args} \
                 --query #{QUERY} \
                 -q \
-                -b #{Shellwords.escape(dir)} \
-                  #{escaped_file_names}
+                -b #{Shellwords.escape(dir)}
               CMD
               cmd = cmd.tr("\n", ' ')
 

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

@@ -10,7 +10,8 @@ module Yard
             self.id = :undocumented_objects
             self.defaults = {
               'Enabled' => true,
-              'Severity' => 'warning'
+              'Severity' => 'warning',
+              'ExcludedMethods' => ['initialize/0']
             }.freeze
             self.combines_with = ['Documentation/UndocumentedBooleanMethods'].freeze
           end