Accept misused :nodoc: usage

オープン
  • 何か問題がありますか？
#1,578 コメント 0 件 リアクション 1 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
35/100
issue の種類
バグ
明瞭さ
おおむね明確
活発さ
停滞
技術スタック
ruby
領域
documentation

調査の方向性

issue 内の Ruby の例を再現ケースとして使用し、RDoc のディレクティブのパースと関連付けの動作を追跡します。現在の処理を、提案されているコンテナ、状況依存、コードオブジェクトのカテゴリと比較し、ディレクティブが混在している場合の警告動作も確認します。例が意図したコンテナまたはコードオブジェクトに解決され、無効な混在について警告されれば完了です。

索引モデルが issue の本文から書いたものです。

説明

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.

主要言語
Ruby
スター
928
フォーク
471
平均マージ
2日 4分
マージ済み PR（30日）
13

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

ruby/rdoc のほかの issue

ruby/rdoc の issue をすべて見る

似ている issue

Ruby の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。