Add RDoc coverage check for C extensions in ruby-core CI#1659
Draft
Add RDoc coverage check for C extensions in ruby-core CI#1659
Conversation
Run `rdoc -C` against ext/io/console in ruby/ruby to catch coverage regressions for C extensions that use :stopdoc: directives.
Collaborator
|
🚀 Preview deployment available at: https://14192af5.rdoc-6cd.pages.dev (commit: a1473b8) |
Use BUNDLE_GEMFILE to ensure the coverage check runs against the locally checked out RDoc, not the system-installed version.
Run coverage in two steps: 1. Full ruby/ruby excluding io-console (must pass - no regressions) 2. io-console only (fails due to stopdoc bug, passes with fix) This proves the failure is isolated to io-console's :stopdoc: handling.
Running from ruby/ruby with .document file present, the coverage check correctly shows only io-console failures (2 undocumented items). The split was unnecessary.
bundle exec changes the gem environment and causes different file processing (5321 items vs 9582 expected), leading to false Prism failures. Using ruby -I matches how tool/rdoc-srcdir overrides the load path in ruby/ruby.
Two fixes: 1. Generate rbconfig.rb first (make update-rbconfig), matching ruby/ruby's rdoc-coverage target prerequisite. 2. Use ruby -I -r instead of exe/rdoc to avoid gem 'rdoc' call that could override the load path with the system rdoc.
Drop rbconfig.rb generation (not needed for coverage) and use ruby -I -S rdoc which matches the local testing approach that correctly shows only io-console failures.
Move the coverage step after make html so the build environment is fully set up. Use make rdoc-coverage matching ruby/ruby's check_misc workflow — build:local_ruby already installs our RDoc into the ruby tree so tool/rdoc-srcdir picks it up.
After parsing a C file, `parse_file` resets `done_documenting = false` on all classes in `top_level.classes_or_modules`. Since `done_documenting=` also sets `@document_self = !value`, this inadvertently resets `document_self` to `true` for classes that had `:stopdoc:` applied during parsing. This became an issue after `add_to_classes_or_modules` was added to the C parser's `handle_class_module`, which caused C-defined classes to appear in `top_level.classes_or_modules` for the first time. The fix skips the `done_documenting` reset for classes where `document_self` is already `false` (set by `:stopdoc:`), preserving the explicit directive.
The real issue: done_documenting= unconditionally sets document_self even when done_documenting isn't actually changing. When parse_file resets done_documenting=false on classes that already have done_documenting=false, it needlessly overrides document_self (which may have been set to false by :stopdoc:). Add an early return when the value isn't changing, so :stopdoc: state is preserved without affecting the :enddoc: reset behavior.
…eset The previous approach (checking done_documenting == value) was too broad and hid 501 items that should remain visible. Instead, track :stopdoc: state with a dedicated @stopped_doc flag. When done_documenting= resets document_self, it skips the reset if @stopped_doc is set. The flag is cleared by :startdoc:. This precisely preserves :stopdoc: directives without affecting classes that need the done_documenting reset for file reopening.
The suppress method calls stop_doc internally but should remain reversible via done_documenting=false. Only the :stopdoc: directive (processed in pre_process.rb) should set the @stopped_doc flag that prevents done_documenting= from overriding document_self.
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
2 participants
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
rdoc -Ccoverage check step againstext/io/consolein the ruby-core CI workflow:stopdoc:directives in C extensions are incorrectly reported as undocumentedContext
This is expected to fail on the current
masterbranch due to a bug wheredone_documenting = falseresetsdocument_selffor classes that had:stopdoc:applied. See #1658 for the fix.Once verified, the fix from #1658 can be cherry-picked here to confirm it resolves the CI failure.
Test plan