Module: Yard::Lint::Validators::Documentation::UndocumentedObjects

Defined in:

lib/yard/lint/validators/documentation/undocumented_objects.rb,
lib/yard/lint/validators/documentation/undocumented_objects/config.rb,
lib/yard/lint/validators/documentation/undocumented_objects/parser.rb,
lib/yard/lint/validators/documentation/undocumented_objects/result.rb,
lib/yard/lint/validators/documentation/undocumented_objects/validator.rb,
lib/yard/lint/validators/documentation/undocumented_objects/messages_builder.rb

Overview

Note:

Exact name matching excludes the method with any arity. If you need arity-specific exclusions, use arity notation instead.

Note:

Arity counts total parameters (required + optional) excluding splat (*) and block (&) parameters.

UndocumentedObjects validator

Checks for missing documentation on classes, modules, and methods. This validator supports flexible method exclusions through the ExcludedMethods configuration option.

Pattern Types

The ExcludedMethods feature supports three pattern types for maximum flexibility:

1. Exact Name Matching

Excludes methods with the specified name, regardless of arity:

ExcludedMethods:
  - 'to_s'           # Excludes ALL to_s methods regardless of parameters
  - 'inspect'        # Excludes ALL inspect methods

2. Arity Notation (method_name/N)

Excludes methods with specific parameter counts:

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

3. Regex Patterns

Excludes methods matching a regular expression:

ExcludedMethods:
  - '/^_/'           # Excludes all methods starting with underscore (private convention)
  - '/^test_/'       # Excludes all test methods
  - '/_(helper|util)$/' # Excludes methods ending with _helper or _util

Configuration Examples

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

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

Defined Under Namespace

Classes: Config, MessagesBuilder, Parser, Result, Validator