How to handle tool-specific magic comments
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 35/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- ruby
- Domain
- documentation
Research direction
The issue names no implementation file or test. Reproduce the example with RDoc, then trace the handling of shebangs and Ruby magic comments and compare it with tool-specific comments such as # typed: true and # rbs_inline: enabled. Done means those comments no longer appear as top-level documentation without breaking RDoc's existing magic-comment behavior.
Written by the indexing model from the issue text.
Description
rdoc currently removes shebangs and ruby magic comments from rendered documetantion.
But other tools like sorbet and rbs-inline provide their own comments like # typed: true or rbs_inline: enabled which aren't excluded. If I have a file like this:
# frozen_string_literal: true
# rbs_inline: enabled
# :markup: markdown
module Prism
module Foo
# ...
end
end
Then for each file, you get one rbs_inline comment on the top-level namespace. I feel like either rdoc should
- ignore any magic-style comment, regardless of if it is "official" or not
- Not attach comments where there is whitespace before the top-level. I guess this is not feasable for backwards compat since rdoc itself makes heavy use of that style.
This can be worked around by inserting #-- before the magic comments but I don't think I should need to care about this at all.
- Dominant language
- Ruby
- Stars
- 930
- Forks
- 472
- Avg merge
- 2d 8h
- Merged PRs (30d)
- 12
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from ruby/rdoc
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
RDoc 8.0.0 gem omits `doc/rdoc/example.rb`, which is referenced by the packaged markup documentationPossibly taken @OskarEichler claimed this 80 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
markdown html excerpt includes link partsPossibly taken @anyingiit claimed this 26 days ago. Open
Difficulty 3/5 1-2 days Newbie friendliness 66/100
Maintainers usually reply within 1 day
-
Regexp generated from unescaped input in #expand_classPossibly taken @jaynetics claimed this 39 days ago. Open
Difficulty 1/5 Under an hour Newbie friendliness 25/100
Maintainers usually reply within 1 day
Similar issues
-
needs verification
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
Maintainers usually reply within 13 days
-
🐛 bug 👩💻 équipe CE 🧑🏭 entreprises
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
betagouv/conseillers-entreprises#4808 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
yosiat/panko_serializer#250 ·