Accept misused :nodoc: usage
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- ruby
- Domain
- documentation
Research direction
Use the Ruby examples in the issue as reproduction cases and trace RDoc's directive parsing and association behavior. Compare current handling with the proposed container, situation-dependent, and code-object categories, including warning behavior for mixed directives. Done means the examples resolve to the intended container or code object and invalid mixes are warned about.
Written by the indexing model from the issue text.
Description
Usage of these :nodoc: are not correct but frequently misused. Maybe it's better to apply :nodoc: to the CodeObject next line.
class Foo
# :nodoc: (This :nodoc: is applied to class Foo, not to method bar)
def bar; end
# :nodoc: (Same as above)
def baz; end
end
Correct usage is:
class Foo
# :nodoc: (for class Foo)
def bar
end
def baz # :nodoc: (for method baz)
end
end
This behavior looks like a bug.
class Foo
# This is a comment for method bar
# :nodoc: (this is a nodoc directive for class Foo)
# :call-seq: bar(x, y) (this is a call-seq directive for method bar)
# This is also a coment for method bar
def bar
end
end
Suggestion
If comment only contains container directive(including :nodoc:) and it appears at first line in class/module, it is a directive for container itself.
class Foo
# :nodoc: (for container)
# :stopdoc: (for container)
def foo; end
end
If a comment before code object contains container directive(except :nodoc:), it's for container
class Foo
...
# :stopdoc: (for container)
def foo; end
end
Other comments are for code object. If it contains container directive(except :nodoc:), it's an error to be warned.
class Foo
# :nodoc: (for method)
# comment
def foo; end
# :nodoc: (for method)
def foo; end
end
Directive categories
Directive categorization will be a bit complicated, but I think it's worth clarifying it.
Container directive
Must not mix with code object directives, comment containing these directives must not associated with code object.
:startdoc: :stopdoc: :enddoc: :doc: :category:
Container special directive
Must not mix with code object directives. Comment text is specially handled.
:section:
Situation dependent directive
Can be both container directive or code object directive
:nodoc:
CodeObject directive
Other directives. :callseq: :yield: and also unknown ones.
- 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 ·