.yard-lint.yml

# YARD-Lint Configuration
# See https://github.com/mensfeld/yard-lint for documentation

# Global settings for all validators
AllValidators:
  YardOptions:
  - "--private"
  - "--protected"
  Exclude:
  - .git/**/*
  - vendor/**/*
  - node_modules/**/*
  - test/**/*
  FailOnSeverity: convention
  MinCoverage: 98.0
  DiffMode:
    DefaultBaseRef:

# Documentation validators
Documentation/UndocumentedObjects:
  Description: Checks for classes, modules, and methods without documentation.
  Enabled: true
  Severity: error
  ExcludedMethods:
  - initialize/0
  - "/^_/"

Documentation/UndocumentedMethodArguments:
  Description: Checks for method parameters without @param tags.
  Enabled: true
  Severity: error

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

Documentation/UndocumentedOptions:
  Description: Detects methods with options hash parameters but no @option tags.
  Enabled: true
  Severity: error

Documentation/MarkdownSyntax:
  Description: Detects common markdown syntax errors in documentation.
  Enabled: true
  Severity: error

Documentation/EmptyCommentLine:
  Description: Detects empty comment lines at the start or end of documentation blocks.
  Enabled: true
  Severity: convention
  EnabledPatterns:
    Leading: true
    Trailing: true

Documentation/BlankLineBeforeDefinition:
  Description: Detects blank lines between YARD documentation and method definition.
  Enabled: true
  Severity: convention
  OrphanedSeverity: convention
  EnabledPatterns:
    SingleBlankLine: true
    OrphanedDocs: true

# Tags validators
Tags/Order:
  Description: Enforces consistent ordering of YARD tags.
  Enabled: true
  Severity: error
  EnforcedOrder:
  - param
  - option
  - return
  - raise
  - example

Tags/InvalidTypes:
  Description: Validates type definitions in @param, @return, @option tags.
  Enabled: true
  Severity: error
  ValidatedTags:
  - param
  - option
  - return

Tags/TypeSyntax:
  Description: Validates YARD type syntax using YARD parser.
  Enabled: true
  Severity: error
  ValidatedTags:
  - param
  - option
  - return
  - yieldreturn

Tags/MeaninglessTag:
  Description: Detects @param/@option tags on classes, modules, or constants.
  Enabled: true
  Severity: error
  CheckedTags:
  - param
  - option
  InvalidObjectTypes:
  - class
  - module
  - constant

Tags/CollectionType:
  Description: Validates Hash collection syntax consistency.
  Enabled: true
  Severity: error
  EnforcedStyle: long
  ValidatedTags:
  - param
  - option
  - return
  - yieldreturn

Tags/TagTypePosition:
  Description: Validates type annotation position in tags.
  Enabled: true
  Severity: error
  CheckedTags:
  - param
  - option
  EnforcedStyle: type_after_name

Tags/ApiTags:
  Description: Enforces @api tags on public objects.
  Enabled: false
  Severity: error
  AllowedApis:
  - public
  - private
  - internal

Tags/OptionTags:
  Description: Requires @option tags for methods with options parameters.
  Enabled: true
  Severity: error

Tags/ExampleSyntax:
  Description: Validates Ruby syntax in @example tags.
  Enabled: true
  Severity: warning

Tags/RedundantParamDescription:
  Description: Detects meaningless parameter descriptions that add no value.
  Enabled: true
  Severity: convention
  CheckedTags:
  - param
  - option
  Articles:
  - The
  - the
  - A
  - a
  - An
  - an
  MaxRedundantWords: 6
  GenericTerms:
  - object
  - instance
  - value
  - data
  - item
  - element
  EnabledPatterns:
    ArticleParam: true
    PossessiveParam: true
    TypeRestatement: true
    ParamToVerb: true
    IdPattern: true
    DirectionalDate: true
    TypeGeneric: true

Tags/InformalNotation:
  Description: Detects informal tag notation patterns like "Note:" instead of @note.
  Enabled: true
  Severity: warning
  CaseSensitive: false
  RequireStartOfLine: true
  Patterns:
    Note: "@note"
    Todo: "@todo"
    TODO: "@todo"
    FIXME: "@todo"
    See: "@see"
    See also: "@see"
    Warning: "@deprecated"
    Deprecated: "@deprecated"
    Author: "@author"
    Version: "@version"
    Since: "@since"
    Returns: "@return"
    Raises: "@raise"
    Example: "@example"

Tags/NonAsciiType:
  Description: Detects non-ASCII characters in type annotations.
  Enabled: true
  Severity: warning
  ValidatedTags:
  - param
  - option
  - return
  - yieldreturn
  - yieldparam

Tags/TagGroupSeparator:
  Description: Enforces blank line separators between different YARD tag groups.
  Enabled: false
  Severity: convention
  TagGroups:
    param:
    - param
    - option
    return:
    - return
    error:
    - raise
    - throws
    example:
    - example
    meta:
    - see
    - note
    - todo
    - deprecated
    - since
    - version
    - api
    yield:
    - yield
    - yieldparam
    - yieldreturn
  RequireAfterDescription: false

# 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: error