使用 YARD 进行 Ruby 文档的内部评论？

Question

我正在将我维护的 ruby​​gem 从 RDoc 切换到 YARD 文档。但是，代码中有一些关键注释只需要保留在代码中，而不应该出现在文档中。例如：

##
# SomeClass documentation here.
#--
# CRITICAL comment that should be in the code but not in the documentation,
#          and must be at this particular spot in the code.
#++
# more documentation that follows the critical comment block, but this part 
# should be in the generated documentation
class SomeClass
    ...
end

RDoc 支持 #-- 和 #++ 门，但 YARD 不支持。在 YARD 标记中执行类似操作的语法（如果存在）是什么？

Answer 1

好吧，以最简单、快速和肮脏的形式，解决方案很容易 -
只需使用任何自定义（码未知）标签名称。例如：

##
# SomeClass documentation here.
#
# @internal_note CRITICAL
#   comment that should be in the code but not in the documentation,
#   and must be at this particular spot in the code.
#
# more documentation that follows the critical comment block, but this part 
# should be in the generated documentation

这里唯一的问题是yard会警告您每次出现@internal_note：

[warn]: Unknown tag @internal_note in file ... near line xxx
[warn]: Unknown tag @internal_note in file ... near line yyy
...

我真的认为应该有官方方法来抑制不需要的警告，但不幸的是我找不到它。不过，您可以尝试以下操作之一：

1. yardoc -q # Problem: will subpurged有用的信息

2. 您可以创建文件 yardinit.rb，其中包含以下内容：

   YARD::Tags::Library.define_tag('内部注释', :internal_note)
   

   然后生成文档

   yardoc -e './yardinit.rb'
   

3. 生成文档

   有一个yard插件可以抑制所有未知标签警告https://github.com/rubyworks/yard-shutup

   它看起来不太活跃，gem installyard-shutup不起作用，但你可以手动安装它并尝试一下

Answer 2

您可以编写

# @comment TODO: This will not be seen
def method(*args)
  ...
end

并在命令行上运行（或将其放入您的 .yardopts 中）

$ yard doc --tag comment --hide-tag comment

Answer 3

您可以使用标识在码注释中隐藏或转换为“注释”：

示例 1：

# Show Text1
# Show Text2
# Show Text3

结果：

Show Text1
Show Text2
Show Text3

示例 2：

# Show Text1
  # Show Text2
  # Show Text3

结果：

Show Text2
Show Text3

示例 3：

  # Show Text1
# Show Text2
# Show Text3

结果：

Show Text2
Show Text3

示例 4：

  # Show Text1
# Show Text2
  # Show Text3

结果：

Show Text3

示例 5：

# Show Text2
  # Show Text1
# Show Text3

结果：

Show Text3

示例 6：

  # Show Text1
#
  # Show Text3

结果：

Show Text3

示例 7：

# Show Text2
  #
# Show Text3

结果：

Show Text3