Skip to content

Refactor comment_location from Array to Hash#1634

Merged
st0012 merged 1 commit intomasterfrom
refactor-comment-location
Mar 5, 2026
Merged

Refactor comment_location from Array to Hash#1634
st0012 merged 1 commit intomasterfrom
refactor-comment-location

Conversation

@st0012
Copy link
Member

@st0012 st0012 commented Mar 5, 2026

Convert ClassModule#comment_location from an Array of [comment, location] pairs to a Hash of { location => [comments] }.

Motivation

When a class like RDoc is documented across multiple files (lib/rdoc.rb, lib/rdoc/rubygems_hook.rb, etc.), each file contributes a comment. With the old Array of [comment, location] pairs, there was no efficient way to look up or replace comments by file. This matters for server live-reload (#1620): when a user edits lib/rdoc.rb, we need to clear that file's comment and re-parse — but preserve comments from other files in their original order. The Array structure made this fragile because removing and re-appending an entry moved it to the end, changing the order comments appeared on the rendered page.

The Hash structure solves this: { location => [comments] } allows O(1) lookup by file, and Ruby hashes preserve insertion order — replacing a key's value keeps it in position.

A secondary benefit: a class reopened in the same file now preserves all its comments:

# comment1
class A; end
# comment2
class A; end

With the old Array, the C parser had a special-case delete_if to deduplicate same-location entries, while Ruby parsers accumulated duplicates inconsistently. With the new Hash, each location maps to an array of comments — both comments are preserved and rendered, matching the cross-file behavior.

Changes

  • add_comment: appends to array per location — (@comment_location[location] ||= []) << comment
  • parse: uses flat_map to flatten per-location comment arrays into Document parts
  • marshal_load / merge: use group_by(&:file) to reconstruct arrays from Documents
  • documented?, search_snippet, from_module: updated for new value shape
  • i18n/text.rb: handles Hash with array values
  • C parser delete_if special case removed (hash key naturally deduplicates by location)

Convert ClassModule#comment_location from an Array of [comment, location]
pairs to a Hash of { location => [comments] }. Each location maps to an
array of comments, so a class reopened in the same file preserves all
its comments in the rendered documentation.

Key changes:
- add_comment appends to an array per location instead of pushing pairs
- C parser special-case delete_if removed (hash key handles dedup)
- parse uses flat_map to flatten per-location comment arrays into docs
- marshal_load/merge use group_by(&:file) to reconstruct arrays
- search_snippet, documented?, from_module updated for new shape
@matzbot
Copy link
Collaborator

matzbot commented Mar 5, 2026

🚀 Preview deployment available at: https://5326d8ea.rdoc-6cd.pages.dev (commit: 791572b)

@st0012 st0012 merged commit f519593 into master Mar 5, 2026
74 checks passed
@st0012 st0012 deleted the refactor-comment-location branch March 5, 2026 15:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants