Adopt yard-lint for structured YARD documentation linting#1190
Draft
myronmarston wants to merge 14 commits into
Draft
Adopt yard-lint for structured YARD documentation linting#1190myronmarston wants to merge 14 commits into
myronmarston wants to merge 14 commits into
Conversation
Replaces the janky regex-based doc coverage check with yard-lint, a structured linter with per-check controls and gradual adoption support. #913 The old `docs_coverage` task parsed YARD's text output to extract coverage % and warning/error counts. Now yard-lint handles doc quality (undocumented objects, tag validation, type checking, etc.) while the renamed `yard_warnings` task retains only YARD parser warning/error detection (e.g. "Undocumentable superclass" from Data.define) which yard-lint doesn't cover. Key details: - yard-lint is invoked via Ruby API (not CLI) so we can register custom YARD tags (@dynamic, @implements) before parsing -- YardOptions in .yard-lint.yml only affects visibility filtering, not tag registration - MinCoverage disabled because yard-lint counts all objects including private ones, which doesn't match YARD's --no-private behavior - .yard-lint-todo.yml baselines 892 existing violations for gradual fix-up across 12 validators Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
yard-lint doesn't respect YARD's @Private tag — it only checks Ruby visibility (public/private/protected). YARD's --no-private verifier checks both `obj.visibility` AND `obj.tag(:private)` (walking up ancestors), but yard-lint's QueryExecutor only does the former. This caused 614 false-positive offenses on @Private classes. Fix: filter offenses in our rake task by checking the YARD registry after yard-lint runs. Regenerate .yard-lint-todo.yml with only the 278 real offenses (down from 892). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove empty trailing comment line in doc block for FromDisk#graphql_schema_string. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Close unclosed backtick in TypeReference#as_static_derived_type doc. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move type annotation after param name per YARD convention:
`@param updates [Hash{Symbol => Object}]` instead of
`@param [Hash<Symbol, Object>] updates`.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace generic "element to check" param description with a more specific one describing what kinds of schema elements are expected. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add docs for Field#highlightable? and Indexing::Field#nullable?. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- `[bool]` → `[Boolean]` (YARD type, not Ruby keyword) - `Array<String, :all>` → `Array<String>, :all` (Array takes one type param; `:all` is an alternate value, not a second type param) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove blank lines between doc comments and their definitions in 5 files. The elasticsearch/opensearch client files remain excluded because their offenses are section header comments (`# Cluster APIs`, etc.) that yard-lint misidentifies as orphaned documentation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add @option tags for methods that accept keyword options: - HasTypeInfo#mapping: document all CUSTOMIZABLE_DATASTORE_PARAMS - HasTypeInfo#json_schema: document common JSON schema keywords - Field#json_schema: document :nullable option - Field#mapping, ScalarType#mapping: note forwarding to HasTypeInfo - HasIndices#initialize: note forwarding to super Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Reorder YARD tags to match enforced order: param, option, yield, yieldparam, yieldreturn, return, raise, see, example, note, todo. The most common fix was moving @note after @example — most methods had @note before @example. Also removed redundant @param/@option tags on methods using `(see ...)` cross-references, since those inherit all tags from the referenced method. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add @option tags and improve @param descriptions for methods with **kwargs. Methods with enumerable options (enum_value, type_namer, namespace_type, graphql_formatter) got specific @option tags. Methods with open-ended pass-through kwargs (api, has_indices, field, config) got improved @param descriptions explaining where the options are forwarded. 7 files remain in the todo for open-ended kwargs where @option tags would be impractical/misleading. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace `Hash<K, V>` with `Hash{K => V}` in all YARD type annotations
per YARD's standard collection type syntax.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add @param tags to 52 files where methods had doc comments but were missing parameter documentation. This was the largest category (106 non-@Private offenses). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adopts yard-lint to lint YARD documentation quality, addressing #913. The old
docs_coveragetask only checked whether public objects had a doc comment at all (100% coverage); yard-lint validates the quality of that documentation — missing@paramtags, invalid type syntax, tag ordering, etc.Infrastructure changes:
yard-lint ~> 1.5gem.yard-lint.ymlconfig and.yard-lint-todo.ymlbaselinesite:yard_lintrake task (calls yard-lint Ruby API to register custom@dynamic/@implementstags before parsing)docs_coverage→yard_warnings(now only checks YARD parser warnings; coverage is handled by yard-lint)@private-tagged objects from yard-lint offenses (yard-lint bug: doesn't respect YARD's@privatetag)Documentation fixes (all 12 categories from the initial baseline):
EmptyCommentLine: remove trailing empty comment lineMarkdownSyntax: close unclosed backtickTagTypePosition: type after param nameRedundantParamDescription: more specific param descriptionUndocumentedObjects: add docs fornullable?andhighlightable?InvalidTypes:[bool]→[Boolean], fixArray<String, :all>BlankLineBeforeDefinition: remove blank lines between doc and defOptionTags: add@optiontags formapping,json_schema, etc.Tags/Order: reorder tags to matchparam, option, yield, return, raise, see, example, noteUndocumentedOptions: add@option/improve@paramfor**kwargsmethodsCollectionType:Hash<K, V>→Hash{K => V}across 32 filesUndocumentedMethodArguments: add@paramtags across 52 filesRemaining in todo (11 entries, all legitimate exceptions):
BlankLineBeforeDefinition(3 files): section-header comments and copyright headers misidentified as orphaned docsTags/OptionTags(1 file):(see ...)cross-reference inherits tags that conflict with local@paramUndocumentedOptions(7 files): open-ended**kwargsforwarded to other systems where enumerating@optiontags is impracticalTest plan
bundle exec rake site:yard_lintpasses (0 offenses)bundle exec rake site:yard_warningspasses (0 unexpected YARD parser warnings)script/lintpasses (0 offenses)GraphQLEndpoint#call, confirmed offense detected)🤖 Generated with Claude Code