Accept misused :nodoc: usage

未关闭
  • 哪里不对？
#1,578 0 条评论 1 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
5/5
预计耗时
一周以上
新手友好度
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 分钟
30 天内合并 PR
13

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

ruby/rdoc 的其他 Issue

查看 ruby/rdoc 的全部 Issue

相似的 Issue

更多 Ruby Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。