YARD-Lint

name: YARD Lint
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Need full history for --diff
      - name: Run YARD-Lint on changed files
        run: bundle exec yard-lint lib/ --diff origin/${{ github.base_ref }}

# .yard-lint.yml
AllValidators:
  # Fail if documentation coverage is below this percentage
  MinCoverage: 80.0

name: Documentation Quality
on: [pull_request]
jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Check documentation coverage for new code
        run: |
          bundle exec yard-lint \
            lib/ \
            --diff origin/${{ github.base_ref }} \
            --min-coverage 90 \
            --quiet

# .yard-lint.yml
# 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/**/*'

  # Exit code behavior (error, warning, convention, never)
  FailOnSeverity: warning

  # Diff mode settings
  DiffMode:
    # Default base ref for --diff (auto-detects main/master if not specified)
    DefaultBaseRef: ~
    # Include untracked files in diff mode (not yet implemented)
    IncludeUntracked: false

# Individual validator configuration
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.'
  Enabled: true
  Severity: warning

Documentation/UndocumentedBooleanMethods:
  Description: 'Checks that question mark methods document their boolean return.'
  Enabled: true
  Severity: warning

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
  ExtraTypes:
    - 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
  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/AbstractMethods:
  Description: 'Ensures @abstract methods do not have real implementations.'
  Enabled: true
  Severity: warning

# Inherit from local files
inherit_from:
  - .yard-lint_todo.yml
  - ../.yard-lint.yml

# Inherit from gems
inherit_gem:
  my-company-style: .yard-lint.yml

# Your project-specific overrides
Documentation/UndocumentedObjects:
  Exclude:
    - 'lib/legacy/**/*'

# .yard-lint.yml
AllValidators:
  Exclude:
    - 'vendor/**/*'

# Exclude legacy files from type validation only
Tags/InvalidTypes:
  Exclude:
    - 'lib/legacy/**/*'
    - 'lib/deprecated/*.rb'

# But still check for undocumented methods in those files
Documentation/UndocumentedObjects:
  Enabled: true

# Strict documentation for public API
Documentation/UndocumentedMethodArguments:
  Enabled: true
  Exclude:
    - 'lib/internal/**/*'
    - 'spec/**/*'

# But enforce @api tags everywhere
Tags/ApiTags:
  Enabled: true
  Exclude:
    - 'spec/**/*'  # Only exclude specs

AllValidators:
  # Default: only parse public methods
  YardOptions: []

# Check all methods (including private) for tag order
Tags/Order:
  YardOptions:
    - --private
    - --protected

# But only require documentation for public methods
Documentation/UndocumentedObjects:
  YardOptions: []  # Only public methods

# 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

- name: Run YARD Lint
  run: bundle exec yard-lint lib/