Adopt yard-lint for structured YARD documentation linting

.yard-lint-todo.yml

@@ -0,0 +1,30 @@
+# This file was auto-generated on 2026-05-15 00:58:28 UTC
+# It contains exclusions for current violations to establish a baseline.
+#
+# To gradually fix violations:
+# 1. Remove files/patterns from the Exclude list below
+# 2. Run yard-lint to see the violations for those files
+# 3. Fix the violations
+# 4. Commit the changes
+
+# Documentation validators
+Documentation/BlankLineBeforeDefinition:
+  Exclude:
+    - "elasticgraph-apollo/lib/elastic_graph/apollo/graphql/engine_extension.rb"
+    - "elasticgraph-elasticsearch/lib/elastic_graph/elasticsearch/client.rb"
+    - "elasticgraph-opensearch/lib/elastic_graph/opensearch/client.rb"
+
+Tags/OptionTags:
+  Exclude:
+    - "elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb"
+
+Documentation/UndocumentedOptions:
+  Exclude:
+    - "elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb"
+    - "elasticgraph-schema_definition/lib/elastic_graph/schema_definition/mixins/has_indices.rb"
+    - "elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb"
+    - "elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/namespace_type.rb"
+    - "elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/type_namer.rb"
+    - "elasticgraph-support/lib/elastic_graph/support/config.rb"
+    - "elasticgraph-support/lib/elastic_graph/support/graphql_formatter.rb"
+

.yard-lint.yml

@@ -0,0 +1,220 @@
+# YARD-Lint Configuration
+# See https://github.com/mensfeld/yard-lint for documentation
+
+inherit_from: .yard-lint-todo.yml
+
+AllValidators:
+  YardOptions:
+    - --no-private
+    - --tag dynamic
+    - --hide-tag dynamic
+    - --tag implements
+    - --hide-tag implements
+    - --markup markdown
+    - --markup-provider redcarpet
+
+  Exclude:
+    - '\.git'
+    - 'vendor/**/*'
+    - 'node_modules/**/*'
+    - 'spec/**/*'
+    - 'spec_support/**/*'
+    - 'test/**/*'
+    - 'tmp/**/*'
+    - 'bundle/**/*'
+    - 'sig/**/*'
+
+  FailOnSeverity: warning
+
+  # yard-lint's coverage metric counts all objects including private ones,
+  # which doesn't match YARD's --no-private behavior. We rely on
+  # Documentation/UndocumentedObjects (which respects --no-private via
+  # YardOptions visibility filtering) to catch undocumented public objects instead.
+  # MinCoverage: 100.0
+
+Documentation/UndocumentedObjects:
+  Enabled: true
+  Severity: warning
+  ExcludedMethods:
+    - 'initialize/0'
+    - '/^_/'
+
+Documentation/UndocumentedMethodArguments:
+  Enabled: true
+  Severity: warning
+
+Documentation/UndocumentedBooleanMethods:
+  Enabled: true
+  Severity: warning
+
+Documentation/UndocumentedOptions:
+  Enabled: true
+  Severity: warning
+
+Documentation/MissingReturn:
+  Enabled: false
+
+Documentation/MarkdownSyntax:
+  Enabled: true
+  Severity: warning
+
+Documentation/EmptyCommentLine:
+  Enabled: true
+  Severity: convention
+
+Documentation/BlankLineBeforeDefinition:
+  Enabled: true
+  Severity: convention
+  OrphanedSeverity: convention
+  EnabledPatterns:
+    SingleBlankLine: true
+    OrphanedDocs: true
+
+Tags/Order:
+  Enabled: true
+  Severity: convention
+  EnforcedOrder:
+    - param
+    - option
+    - yield
+    - yieldparam
+    - yieldreturn
+    - return
+    - raise
+    - see
+    - example
+    - note
+    - todo
+
+Tags/InvalidTypes:
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+
+Tags/TypeSyntax:
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/MeaninglessTag:
+  Enabled: true
+  Severity: warning
+  CheckedTags:
+    - param
+    - option
+  InvalidObjectTypes:
+    - class
+    - module
+    - constant
+
+Tags/CollectionType:
+  Enabled: true
+  Severity: convention
+  EnforcedStyle: long
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+
+Tags/TagTypePosition:
+  Enabled: true
+  Severity: convention
+  CheckedTags:
+    - param
+    - option
+  EnforcedStyle: type_after_name
+
+Tags/ApiTags:
+  Enabled: false
+
+Tags/OptionTags:
+  Enabled: true
+  Severity: warning
+
+Tags/ExampleSyntax:
+  Enabled: true
+  Severity: warning
+
+Tags/ExampleStyle:
+  Enabled: false
+
+Tags/RedundantParamDescription:
+  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:
+  Enabled: false
+
+Tags/NonAsciiType:
+  Enabled: true
+  Severity: warning
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+    - yieldparam
+
+Tags/TagGroupSeparator:
+  Enabled: false
+
+Tags/ForbiddenTags:
+  Enabled: false
+
+Warnings/UnknownTag:
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownDirective:
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidTagFormat:
+  Enabled: true
+  Severity: error
+
+Warnings/DuplicatedParameterName:
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownParameterName:
+  Enabled: true
+  Severity: error
+
+Semantic/AbstractMethods:
+  Enabled: true
+  Severity: warning

Gemfile

@@ -64,6 +64,7 @@ group :site do
 
   gem "yard", "~> 0.9", ">= 0.9.43"
   gem "yard-doctest", "~> 0.1", ">= 0.1.17"
+  gem "yard-lint", "~> 1.5"
   gem "yard-markdown", "~> 0.7", ">= 0.7.1"
   gem "irb", "~> 1.18" # Needed for yard on Ruby 4.0
 end

Gemfile.lock

@@ -654,6 +654,9 @@ GEM
     yard-doctest (0.1.17)
       minitest
       yard
+    yard-lint (1.5.1)
+      yard (~> 0.9)
+      zeitwerk (~> 2.6)
     yard-markdown (0.7.1)
       csv
       rdoc
@@ -737,6 +740,7 @@ DEPENDENCIES
   vcr (~> 6.4)
   yard (~> 0.9, >= 0.9.43)
   yard-doctest (~> 0.1, >= 0.1.17)
+  yard-lint (~> 1.5)
   yard-markdown (~> 0.7, >= 0.7.1)
 
 CHECKSUMS
@@ -958,6 +962,7 @@ CHECKSUMS
   webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
   yard (0.9.43) sha256=cf8733a8f0485df2a162927e9b5f182215a61f6d22de096b8f402c726a1c5821
   yard-doctest (0.1.17) sha256=7cb35a75d99f58fc42ee72d3542a36e227237b621a40aebc391c95988b72847f
+  yard-lint (1.5.1) sha256=41d194855b4f54aa957a0337720c6f48e252e4a31d7412c46cc94a12399c0149
   yard-markdown (0.7.1) sha256=06c378632dfe7ba053be9ba469eb4701aa0470e36bcf7e5546f353eb90c1bfd1
   yell (2.2.2) sha256=1d166f3cc3b6dc49a59778ea7156ed6d8de794c15106d48ffd6cbb061b9b26bc
   zeitwerk (2.7.5) sha256=d8da92128c09ea6ec62c949011b00ed4a20242b255293dd66bf41545398f73dd