Question

我正在将我从RDoc维护的rubygem切换到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

你可以写

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

在命令行上运行（或将其放入.yardopts）

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

Answer 2

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

##
# 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

这里唯一的问题是院子会警告你每次出现@internal_note：

[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'

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

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

Answer 3

您可以使用标识隐藏或转换为＆＃34;评论＆＃34;在院子里评论：

示例1：

//this works fine
char * name = "John";
name = "Doe";

结果：

# Show Text1
# Show Text2
# Show Text3

示例2：

Show Text1
Show Text2
Show Text3

结果：

# Show Text1
  # Show Text2
  # Show Text3

示例3：

Show Text2
Show Text3

结果：

  # Show Text1
# Show Text2
# Show Text3

示例4：

Show Text2
Show Text3

结果：

  # Show Text1
# Show Text2
  # Show Text3

示例5：

Show Text3

结果：

# Show Text2
  # Show Text1
# Show Text3

示例6：

Show Text3

结果：

  # Show Text1
#
  # Show Text3

示例7：

Show Text3

结果：

# Show Text2
  #
# Show Text3

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

3 个答案: