ruby - 使用 YARD 时忽略注释掉的代码

Question

我有一些如下所示的 Ruby 代码:

# some_string = "{really?}"

大括号需要是字符串的一部分。这一行是注释掉的代码，我想保留在那里。我还使用 YARD 来记录代码，所以当我运行 yard doc 时，它(自然地)会发出无法“真正”链接的警告。

有没有办法让 YARD 忽略注释掉的代码？

Answer 1

Is there a way I can tell YARD to ignore commented out code?

一方面，YARD 记录支持 Rdoc 标记。并且 Rdoc 被记录为支持几种隐藏部件的方法。

RDoc stops processing comments if it finds a comment line startingwith -- right after the # character (otherwise, it will be treated asa rule if it has three dashes or more). This can be used to separateexternal from internal comments, or to stop a comment being associatedwith a method, class, or module. Commenting can be turned back on witha line that starts with ++.

:stopdoc: / :startdoc:
Stop and start adding new documentation elements to the currentcontainer. For example, if a class has a number of constants that youdon’t want to document, put a :stopdoc: before the first, and a:startdoc: after the last. If you don’t specify a :startdoc: by the endof the container, disables documentation for the rest of the currentfile.

Source

另一方面，我从未说服 Rdoc 或 YARD 遵循该标记。如果你的运气比我好，你可以在这里停止阅读。

如果您也无法说服 YARD 遵循该标记，我认为您最好的选择可能是剪掉该行，并使用独特的提交消息提交文件——您将能够找到通过 grep 源代码控制日志轻松实现。

最后，rake让您以任意方式转换文本(代码)文件。您可以编写一个 Rakefile 来删除行，然后再通过 YARD 处理它们。

$ cat silly-ruby-file.src 
class Something

  def this_method
  end

  def that_method
    # some_string = "{really?}" # Hide me
  end
end

我附加了文本 # Hide me；过滤特定文本比过滤任意代码的注释行要容易很多。

$ cat Rakefile
task :default => "silly-ruby-file.rb"
sh "grep -v '# Hide me' silly-ruby-file.src > silly-ruby-file.rb"

这会告诉 rake 运行 grep，将除了带有文本“# Hide me”的行之外的所有行复制到标准输出，它被重定向到“silly-ruby-文件.rb”。