Skip to content

Fix :stopdoc: directive being undone for C-defined classes#1658

Open
st0012 wants to merge 1 commit intomasterfrom
fix-stopdoc-reset-in-c-parser
Open

Fix :stopdoc: directive being undone for C-defined classes#1658
st0012 wants to merge 1 commit intomasterfrom
fix-stopdoc-reset-in-c-parser

Conversation

@st0012
Copy link
Member

@st0012 st0012 commented Mar 22, 2026

Summary

  • 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 tracks :stopdoc: directives with a @stopped_doc flag so done_documenting= preserves the stopdoc state

Reproduction

Run rdoc -C against a C extension that uses :stopdoc: around class definitions, such as io-console:

$ rdoc -C
The following items are not documented:

  class IO::ConsoleMode
  end

  module IO::generic_readable
  end

These classes are intentionally wrapped in /* :stopdoc: */ / /* :startdoc: */ and should not appear in coverage.

@matzbot
Copy link
Collaborator

matzbot commented Mar 22, 2026

🚀 Preview deployment available at: https://ac9127d7.rdoc-6cd.pages.dev (commit: 2bce391)

@st0012 st0012 force-pushed the fix-stopdoc-reset-in-c-parser branch 5 times, most recently from 8269e21 to ff2898f Compare March 22, 2026 23:09
@st0012 st0012 added the bug label Mar 22, 2026
@st0012 st0012 marked this pull request as ready for review March 22, 2026 23:27
After parsing, `parse_file` resets `done_documenting = false` on all
classes in `top_level.classes_or_modules`. The `done_documenting=`
setter unconditionally sets `document_self = !value`, which overrides
the `document_self = false` state set by `:stopdoc:`.

This became visible after `add_to_classes_or_modules` was added to the
C parser's `handle_class_module`, causing C-defined classes to appear
in `top_level.classes_or_modules` for the first time.

Fix by tracking when `:stopdoc:` is explicitly used via a `@stopped_doc`
flag. The `done_documenting=` setter skips the `document_self` override
when this flag is set. The flag is:
- Set only when the `:stopdoc:` directive is processed
- Cleared by `:startdoc:`
- NOT set by `suppress` (which calls `stop_doc` internally but should
  remain reversible via `done_documenting = false`)
@st0012 st0012 force-pushed the fix-stopdoc-reset-in-c-parser branch from ff2898f to 2bce391 Compare March 23, 2026 00:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants