使用YARD for Ruby文档的内部注释？

我正在将我维护的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的标记中做类似事情的语法是什么（如果存在的话）？

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

##
# 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_注释的每次出现向您发出警告：

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

我真的认为应该有官方的方法来压制不受欢迎的警告，但不幸的是我找不到。但是，您可以尝试以下方法之一：

yardoc-q

#问题：也会抑制有用的信息

您可以创建包含以下内容的文件

yardinit.rb

：

YARD::Tags::Library.define_tag('INTERNAL NOTE', :internal_note)

然后使用

yardoc -e './yardinit.rb'

有一个码插件来抑制所有未知标签警告

它看起来不是很有活力，而且

gem install yard shutup

不起作用，但您可以手动安装并尝试一下

你可以写

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

并在命令行上运行（或将其放入

.yardopts

）

---

您可以使用标识隐藏或转换为院子注释中的“注释”：

例1：

# Show Text1
# Show Text2
# Show Text3

结果:

Show Text1
Show Text2
Show Text3

Show Text2
Show Text3

Show Text2
Show Text3

Show Text3

Show Text3

Show Text3

Show Text3

例2：

# Show Text1
  # Show Text2
  # Show Text3

结果:

Show Text1
Show Text2
Show Text3

Show Text2
Show Text3

Show Text2
Show Text3

Show Text3

Show Text3

Show Text3

Show Text3

例3：

  # Show Text1
# Show Text2
# Show Text3

结果:

Show Text1
Show Text2
Show Text3

Show Text2
Show Text3

Show Text2
Show Text3

Show Text3

Show Text3

Show Text3

Show Text3

例4：

  # Show Text1
# Show Text2
  # Show Text3

结果:

Show Text1
Show Text2
Show Text3

Show Text2
Show Text3

Show Text2
Show Text3

Show Text3

Show Text3

Show Text3

Show Text3

例5：

# Show Text2
  # Show Text1
# Show Text3

结果:

Show Text1
Show Text2
Show Text3

Show Text2
Show Text3

Show Text2
Show Text3

Show Text3

Show Text3

Show Text3

Show Text3

例6：

  # Show Text1
#
  # Show Text3

结果:

Show Text1
Show Text2
Show Text3

Show Text2
Show Text3

Show Text2
Show Text3

Show Text3

Show Text3

Show Text3

Show Text3

例7：

# Show Text2
  #
# Show Text3

结果:

Show Text1
Show Text2
Show Text3

Show Text2
Show Text3

Show Text2
Show Text3

Show Text3

Show Text3

Show Text3

Show Text3

---

谢谢，这就解决了我的问题。对不起，我花了这么长时间才接受！有趣的方法和创造性的解决方案，谢谢。