3

我有兴趣记录我的代码，其中大部分是我不创建新类的脚本。

从阅读YARD文档并尝试实际实现一些 YARD 文档，您似乎在定义的类中声明了您的 YARD 标签。当我创建一个类或向一个类添加新方法时，我已经成功地使用了 YARD，如下面的示例代码所示，我还能够使用 YARD 标签（如@author和）记录简单的事情@example。

#!/usr/bin/env ruby -wKU

## a YARD test

class String

  # Prints a string using two supplied strings
  #
  # @param str1 [String] A string to print
  # @param str2 [String] A string to print
  # @return [String] A printed string
  def yardTest(str1, str2)
    p sprintf("Hello, %s, %s", str1, str2)
  end   

end

在此处输入图像描述

我的问题是：

  1. 有没有办法在不定义类的情况下使用 YARD 标签来记录代码（尤其是方法）？
  2. 如果没有，除了在我的代码中添加大量注释之外，还有哪些解决方案？
4

1 回答 1

2

只需像记录任何基于类或模块的方法一样记录脚本中的方法。YARD 应该将它们记录为“顶级命名空间”的一部分。

对您的脚本进行以下修改即可，删除class String包装器：

#!/usr/bin/env ruby -wKU

# Prints a string using two supplied strings
#
# @param str1 [String] A string to print
# @param str2 [String] A string to print
# @return [String] A printed string
def yardTest(str1, str2)
  p sprintf("Hello, %s, %s", str1, str2)
end

您可能还需要考虑为其用户记录脚本的 API，这当然是为了不同的目的和受众。

还要考虑将命令行界面与执行操作的方法分开——在这种情况下，您最终将创建合适的模块和类。当使任何远程复杂的事情变得复杂时，这是一种自然模式，并且允许您将来在脚本之间共享您的逻辑，或者可能共享到不从命令行调用的事物中。您可以看一下thorgem - 它是一个用于创建命令行脚本的框架，并包含遵循良好抽象模式的命令行接口示例。Thor 支持在命令行脚本中轻松包含标准实践用法和帮助。

于 2013-10-19T11:00:04.947 回答