Accept misused :nodoc: usage

Open
#1,578 0 comments 1 reaction 0 assignees View on GitHub

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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ruby/rdoc

All issues in ruby/rdoc

Similar issues

More Ruby issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.