yard-lint 0.2.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5280398682e2734071bcc16923641d1bab52f6bb60c1a1eca5b8bac376a34597
-  data.tar.gz: 9ffa6ccbe7c6f421d9dddb05434cc599b7c02b4d11d9e8e8c28596ac2bdd2713
+  metadata.gz: 95017b70fd77952580b3bf10466c79efff2fb1bbd353d1ba49ce84eab7feb5e9
+  data.tar.gz: 0e5015d8cd2b15b38ccc98d149b3b923997c3952ccc8d799050e51e226d8f14b
 SHA512:
-  metadata.gz: 12c3d102ad7206634975f5052903863bf8ef903d1453a519c1cd12e541f5df8cc39d235df587569270caded90f3d0768b069a29d9c1d54a95be376babe0e673b
-  data.tar.gz: a95efd41ebadda31178a95555e68343999f0edbf5197033a763796383b2fbd124f14bb1010601b1f56c98d41d6bae718bf1b9da21cc6c19aeab6ef97a5ff8e19
+  metadata.gz: d4825147326c85f9af2faaa95200f797321e06d12bbfe4063ea5b0acd851496bc541546d0885ccdd3d674242670a573be396bc4ae454361a266cadc240c813e8
+  data.tar.gz: cb1fa4762efdbecfc0265791a93ffb3ef4a9668e9a6905da29acb966f3bbd650ebd7b21ccb826a5dab2dd972762d4f642e17ecccd986d22354af4837633991cd

data/CHANGELOG.md

@@ -1,4 +1,76 @@
-# Changelog
+# YARD-Lint Changelog
+
+## 1.1.0 (2025-11-11)
+- **[Feature]** Add `Tags/ExampleSyntax` validator to validate Ruby syntax in `@example` tags
+  - Uses Ruby 3.2's `RubyVM::InstructionSequence.compile()` to parse example code
+  - Automatically strips output indicators (`#=>`) before validation
+  - Intelligently skips incomplete single-line snippets (e.g., `multiply(3, 4)`)
+  - Reports multi-line syntax errors with full context from Ruby's parser
+  - Enabled by default with 'warning' severity
+  - Helps prevent broken code examples in documentation
+- **[Feature]** Add `Tags/RedundantParamDescription` validator to detect meaningless parameter descriptions
+  - Detects 7 types of redundant patterns: article+param, possessive, type restatement, param-to-verb, ID pattern, directional date, type+generic
+  - Configurable pattern toggles to enable/disable individual pattern types
+  - Word count threshold (`MaxRedundantWords`: 6) prevents false positives on longer descriptions
+  - Character length threshold (`MinMeaningfulLength`: 15) for additional context
+  - Configurable articles list (`Articles`: The, the, A, a, An, an)
+  - Configurable generic terms list (`GenericTerms`: object, instance, value, data, item, element)
+  - Pattern-specific error messages with actionable suggestions
+  - EXACT pattern matching (not prefix) to avoid false positives
+  - Enabled by default with 'convention' severity
+  - Helps maintain high-quality, meaningful documentation
+- **[Feature]** Add `--init` command to generate `.yard-lint.yml` configuration file with sensible defaults
+- **[Feature]** Add `--force` flag to overwrite existing config file when using `--init`
+- **[Feature]** Add `EnforcedStyle` configuration option to `Tags/CollectionType` validator for bidirectional style enforcement
+  - Supports 'long' style: `Hash{K => V}` (default, standard YARD syntax)
+  - Supports 'short' style: `{K => V}` (Ruby-like syntax without Hash prefix)
+  - Automatically detects violations in either direction and suggests correct style
+  - Updated messages to show correct suggestion based on enforced style
+- **[Feature]** Add `Documentation/UndocumentedOptions` validator to detect methods with options hash parameters but no @option tags
+  - Detects `options = {}`, `opts = {}`, `**kwargs`, and similar patterns
+  - Helps catch missing documentation for option hash parameters
+  - Configurable via `Documentation/UndocumentedOptions` in config
+- **[Feature]** Add `Documentation/MarkdownSyntax` validator to detect common markdown syntax errors in documentation
+  - Detects unclosed backticks in inline code
+  - Detects unclosed code blocks (```)
+  - Detects unclosed bold formatting (**)
+  - Detects invalid list markers (• instead of - or *)
+  - Configurable via `Documentation/MarkdownSyntax` in config
+- [Enhancement] Simplify README by condensing alternative style examples
+- [Documentation] Add Quick Start section to README with `--init` command
+- [Documentation] Update CLI help to show new `--init` and `--force` options
+
+## 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. 

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,11 +22,17 @@ 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
 - **Option hash documentation**: Validate that methods with options parameters have @option tags
+- **Example code syntax validation**: Validates Ruby syntax in `@example` tags to catch broken code examples
+- **Redundant parameter descriptions**: Detects meaningless parameter descriptions that add no value (e.g., `@param user [User] The user`)
 - **YARD warnings**: Unknown tags, invalid directives, duplicated parameter names, and more
 
 ## Installation
@@ -46,6 +57,16 @@ gem install yard-lint
 
 ## Usage
 
+### Quick Start
+
+Generate a default configuration file:
+
+```bash
+yard-lint --init
+```
+
+This creates `.yard-lint.yml` with sensible defaults in your current directory.
+
 ### Command Line
 
 Basic usage:
@@ -62,6 +83,10 @@ yard-lint --config config/yard-lint.yml lib/
 
 # Output as JSON
 yard-lint --format json lib/ > report.json
+
+# Generate config file (use --force to overwrite existing)
+yard-lint --init
+yard-lint --init --force
 ```
 
 ## Configuration
@@ -96,6 +121,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 +163,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,14 +373,22 @@ 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` |
+| `Documentation/UndocumentedOptions` | Detects methods with options hash/kwargs parameters but no `@option` tags | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
+| `Documentation/MarkdownSyntax` | Detects common markdown syntax errors in documentation (unclosed backticks, invalid list markers, etc.) | 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` |
+| `Tags/ExampleSyntax` | Validates Ruby syntax in `@example` tags to catch broken code examples | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
+| `Tags/RedundantParamDescription` | Detects meaningless parameter descriptions that add no value beyond the parameter name | Enabled (convention) | `Enabled`, `Severity`, `Exclude`, `CheckedTags`, `Articles`, `MaxRedundantWords`, `MinMeaningfulLength`, `GenericTerms`, `EnabledPatterns` |
 | **Warnings Validators** |
 | `Warnings/UnknownTag` | Detects unknown YARD tags | Enabled (error) | `Enabled`, `Severity`, `Exclude` |
 | `Warnings/UnknownDirective` | Detects unknown YARD directives | Enabled (error) | `Enabled`, `Severity`, `Exclude` |
@@ -315,6 +399,42 @@ Supported glob patterns:
 | **Semantic Validators** |
 | `Semantic/AbstractMethods` | Ensures `@abstract` methods don't have real implementations | Enabled (warning) | `Enabled`, `Severity`, `Exclude` |
 
+### Detailed Validator Documentation
+
+For detailed documentation on each validator including configuration examples, pattern types, and troubleshooting guides, see the validator module documentation:
+
+- Each validator module file in `lib/yard/lint/validators/` contains comprehensive YARD documentation
+- You can browse the source files directly, or generate YARD documentation to view in HTML format:
+
+```bash
+yard doc lib/yard/lint/validators/**/*.rb
+yard server
+```
+
+Then open http://localhost:8808 in your browser to browse the full validator documentation with examples.
+
+### Quick Configuration Examples
+
+```yaml
+# Exclude specific methods from documentation requirements
+Documentation/UndocumentedObjects:
+  ExcludedMethods:
+    - 'initialize/0'       # Parameter-less constructors
+    - '/^_/'               # Private methods (by convention)
+    - 'to_s'               # String conversion
+
+# Enable @api tag validation (disabled by default)
+Tags/ApiTags:
+  Enabled: true
+  AllowedApis:
+    - public
+    - private
+
+# Disable a validator
+Tags/RedundantParamDescription:
+  Enabled: false
+```
+
 ### Global Configuration
 
 | Option | Description | Default | Type |
@@ -361,94 +481,6 @@ Options:
 
 All configuration (tag order, exclude patterns, severity levels, validator settings) should be defined in `.yard-lint.yml`.
 
-## Examples
-
-### Check a directory
-
-```bash
-yard-lint lib/
-```
-
-### Check a single file
-
-```bash
-yard-lint lib/my_class.rb
-```
-
-### Use custom config file
-
-```bash
-yard-lint --config config/yard-lint.yml lib/
-```
-
-### Configure fail-on-severity
-
-Add to `.yard-lint.yml`:
-```yaml
-AllValidators:
-  FailOnSeverity: error  # Only fail on errors, not warnings
-```
-
-### Enable @api tag validation
-
-Add to `.yard-lint.yml`:
-```yaml
-Tags/ApiTags:
-  Enabled: true
-  AllowedApis:
-    - public
-    - private
-```
-
-This will enforce that all public classes, modules, and methods have an `@api` tag:
-
-```ruby
-# Good
-# @api public
-class MyClass
-  # @api public
-  def public_method
-  end
-
-  # @api private
-  def internal_helper
-  end
-end
-
-# Bad - missing @api tags
-class AnotherClass
-  def some_method
-  end
-end
-```
-
-### @option tag validation (enabled by default)
-
-This validator ensures that methods with options parameters document them. It's **enabled by default**. To disable it, add to `.yard-lint.yml`:
-
-```yaml
-Tags/OptionTags:
-  Enabled: false
-```
-
-Examples:
-
-```ruby
-# Good
-# @param name [String] the name
-# @param options [Hash] configuration options
-# @option options [Boolean] :enabled Whether to enable the feature
-# @option options [Integer] :timeout Timeout in seconds
-def configure(name, options = {})
-end
-
-# Bad - missing @option tags
-# @param name [String] the name
-# @param options [Hash] configuration options
-def configure(name, options = {})
-end
-```
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/yard-lint

@@ -32,6 +32,14 @@ OptionParser.new do |opts|
     options[:progress] = value
   end
 
+  opts.on('--init', 'Generate .yard-lint.yml config file with defaults') do
+    options[:init] = true
+  end
+
+  opts.on('--force', 'Force overwrite when using --init') do
+    options[:force] = true
+  end
+
   opts.on('-v', '--version', 'Show version') do
     puts "yard-lint #{Yard::Lint::VERSION}"
     exit
@@ -43,6 +51,18 @@ OptionParser.new do |opts|
   end
 end.parse!
 
+# Handle --init flag
+if options[:init]
+  if Yard::Lint::ConfigGenerator.generate(force: options[:force])
+    puts 'Created .yard-lint.yml with default configuration'
+    exit 0
+  else
+    puts 'Error: .yard-lint.yml already exists'
+    puts 'Use --init --force to overwrite'
+    exit 1
+  end
+end
+
 # Get path argument
 path = ARGV[0]
 
@@ -52,6 +72,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
@@ -165,8 +199,6 @@ module Yard
         respond_to?(key) ? send(key) : nil
       end
 
-      private
-
       # Generic helper to set validator configuration
       # @param validator_name [String] full validator name (e.g., 'Tags/Order')
       # @param key [String] configuration key

data/lib/yard/lint/config_generator.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Yard
+  module Lint
+    # Generates default .yard-lint.yml configuration file
+    class ConfigGenerator
+      # Default configuration template
+      DEFAULT_CONFIG = <<~YAML
+        # YARD-Lint Configuration
+        # See https://github.com/mensfeld/yard-lint for documentation
+
+        # Global settings for all validators
+        AllValidators:
+          # YARD command-line options (applied to all validators by default)
+          YardOptions:
+            - --private
+            - --protected
+
+          # Global file exclusion patterns
+          Exclude:
+            - '\\.git'
+            - 'vendor/**/*'
+            - 'node_modules/**/*'
+            - 'spec/**/*'
+            - 'test/**/*'
+
+          # Exit code behavior (error, warning, convention, never)
+          FailOnSeverity: warning
+
+        # Documentation validators
+        Documentation/UndocumentedObjects:
+          Description: 'Checks for classes, modules, and methods without documentation.'
+          Enabled: true
+          Severity: warning
+          ExcludedMethods:
+            - 'initialize/0'  # Exclude parameter-less initialize
+            - '/^_/'          # Exclude private methods (by convention)
+
+        Documentation/UndocumentedMethodArguments:
+          Description: 'Checks for method parameters without @param tags.'
+          Enabled: true
+          Severity: warning
+
+        Documentation/UndocumentedBooleanMethods:
+          Description: 'Checks that question mark methods document their boolean return.'
+          Enabled: true
+          Severity: warning
+
+        Documentation/UndocumentedOptions:
+          Description: 'Detects methods with options hash parameters but no @option tags.'
+          Enabled: true
+          Severity: warning
+
+        Documentation/MarkdownSyntax:
+          Description: 'Detects common markdown syntax errors in documentation.'
+          Enabled: true
+          Severity: warning
+
+        # Tags validators
+        Tags/Order:
+          Description: 'Enforces consistent ordering of YARD tags.'
+          Enabled: true
+          Severity: convention
+          EnforcedOrder:
+            - param
+            - option
+            - return
+            - raise
+            - example
+
+        Tags/InvalidTypes:
+          Description: 'Validates type definitions in @param, @return, @option tags.'
+          Enabled: true
+          Severity: warning
+          ValidatedTags:
+            - param
+            - option
+            - return
+
+        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 consistency.'
+          Enabled: true
+          Severity: convention
+          EnforcedStyle: long  # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
+          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
+          Severity: warning
+          AllowedApis:
+            - public
+            - private
+            - internal
+
+        Tags/OptionTags:
+          Description: 'Requires @option tags for methods with options parameters.'
+          Enabled: true
+          Severity: warning
+
+        # Warnings validators - catches YARD parser errors
+        Warnings/UnknownTag:
+          Description: 'Detects unknown YARD tags.'
+          Enabled: true
+          Severity: error
+
+        Warnings/UnknownDirective:
+          Description: 'Detects unknown YARD directives.'
+          Enabled: true
+          Severity: error
+
+        Warnings/InvalidTagFormat:
+          Description: 'Detects malformed tag syntax.'
+          Enabled: true
+          Severity: error
+
+        Warnings/InvalidDirectiveFormat:
+          Description: 'Detects malformed directive syntax.'
+          Enabled: true
+          Severity: error
+
+        Warnings/DuplicatedParameterName:
+          Description: 'Detects duplicate @param tags.'
+          Enabled: true
+          Severity: error
+
+        Warnings/UnknownParameterName:
+          Description: 'Detects @param tags for non-existent parameters.'
+          Enabled: true
+          Severity: error
+
+        # Semantic validators
+        Semantic/AbstractMethods:
+          Description: 'Ensures @abstract methods do not have real implementations.'
+          Enabled: true
+          Severity: warning
+      YAML
+
+      # Generate .yard-lint.yml file in current directory
+      # @param force [Boolean] overwrite existing file if true
+      # @return [Boolean] true if file was created, false if already exists
+      def self.generate(force: false)
+        config_path = File.join(Dir.pwd, Config::DEFAULT_CONFIG_FILE)
+
+        if File.exist?(config_path) && !force
+          false
+        else
+          File.write(config_path, DEFAULT_CONFIG)
+          true
+        end
+      end
+    end
+  end
+end

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] = [] }