Standardize table and heading markup elements #1389
Conversation
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
vinistock
added
the
refactor
|
🚀 Preview deployment available at: https://a3db9c6e.rdoc-6cd.pages.dev (commit: e077b2b) |
tompng
reviewed
Jul 13, 2025
| markup = Markup.new | ||
| markup.add_regexp_handling CrossReference::CROSSREF_REGEXP, :CROSSREF | ||
|
|
||
| @to_html = Markup::ToHtml.new nil |
There was a problem hiding this comment.
I think it should be a local variable here @to_html → to_html
It will be assigned to @to_html at @to_html ||= begin
tompng
approved these changes
Jul 13, 2025
kou
approved these changes
Jul 14, 2025
Comment on lines
+48
to
+50
| @level = level | ||
| @text = text | ||
| super() |
There was a problem hiding this comment.
Initializing the base object (Markup::Element) before this object may be better:
Suggested change
| @level = level | |
| @text = text | |
| super() | |
| super() | |
| @level = level | |
| @text = text |
Or we may want to remove super() here because the current Markup::Element#initialize is empty.
| # HTML markup of the text of this label without the surrounding header element. | ||
| #: () -> String | ||
| def plain_html | ||
| text = self.text.dup |
There was a problem hiding this comment.
It seems that we don't need dup here.
Comment on lines
+82
to
+88
| text = self.text.dup | ||
|
|
||
| if matched = text.match(/rdoc-image:[^:]+:(.*)/) | ||
| text = matched[1] | ||
| end | ||
|
|
||
| self.class.to_html.to_html(text) |
There was a problem hiding this comment.
How about using more descriptive local variable name and remove self. from self.text something like:
Suggested change
| text = self.text.dup | |
| if matched = text.match(/rdoc-image:[^:]+:(.*)/) | |
| text = matched[1] | |
| end | |
| self.class.to_html.to_html(text) | |
| no_image_text = text | |
| if matched = no_image_text.match(/rdoc-image:[^:]+:(.*)/) | |
| no_image_text = matched[1] | |
| end | |
| self.class.to_html.to_html(no_image_text) |
st0012
reviewed
Jul 14, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
I noticed that Markup elements are currently not standardized in any way - even though the code does make some assumptions.
For example, there are visitors that depend on all elements implementing
accept, but no parent class or interface that will help guarantee every element implements it. Some elements are implemented as structs, while other are classes. Some have parent classes for shared functionality and APIs and others don't.I propose that we standardize the markup elements a bit more, so that we can have a common interface for them. It will make it easier for the RDoc to Markdown translator if we can enforce that every markup element has to be able to print itself in Markdown - and I believe the code will be easier to understand too.
This PR creates a base
Markup::Elementclass and I standardizedHeadingandTableas an example. I'm also finding it challenging to understand the logic with no clue about what types are and what is expected from each method, so I also propose we annotate some of these as documentation - even if we're not adopting type checking.If folks agree, I will continue to standardize more markup elements. I'm trying to document what each element represents along the way.