ruby - 使用 YARD for 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 # 问题:也会抑制有用的信息

2. 您可以创建文件yardinit.rb，内容如下:

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

   然后用

   生成文档

   yardoc -e './yardinit.rb'
   

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

   看起来不太活泼，而且gem install yard-shutup也不行，不过你可以手动安装试试看