在Ruby文档中使用YARD的内部评论？

Question

我正在将我维护的rubygem从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:将抑制有用的信息too
2. 您可以创建包含以下内容的文件yardinit.rb：

YARD：：Tags：：Library.define_tag(‘内部备注’，:internal_note)

然后生成文档

yardoc './yardinit.rb'

• there -e https://github.com/rubyworks/yard-shutup是一个yard插件，用于抑制所有未知的标签警告代码

它看起来不是很活跃，gem install yard-shutup也不能工作，但您可以手动安装它，并试用一下

Answer 2

你可以写

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

并在命令行上运行(或将其放入.yardopts中)

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

Answer 3

您可以使用identation来隐藏或转换为码位注释中的“注释”：

示例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