YardRuby 文档工具-轻识

YARD 是一个 Ruby 文档生成工具。它使用户能够生成一致的、可用的文档，这些文档可以非常容易地导出为多种格式，并且还支持扩展自定义Ruby结构，如自定义类级定义。

特点：

1. RDoc / SimpleMarkup格式兼容性：使YARD与RDoc格式兼容。实际上，YARD不会对RDoc文档字符串进行任何处理，并将其留给输出生成工具来决定如何呈现文档。

2. Yardoc元标记格式像Python，Java，Objective-C和其他语言一样：YARD在常规代码文档旁边为元标记使用'@tag'样式定义语法。这些标签应该能够愉快地并排放置RDoc格式的文档，但是提供了一种更一致和可用的方式来描述有关对象的重要信息，例如它们采用什么参数以及它们期望是什么类型，什么方法应该返回，它会引发什么异常，如果过时了，等等。它还允许在输出生成阶段更好地（更一致地）组织信息。您可以在Tags.md文件中找到标签列表。

YARD还支持某些标签的可选“类型”声明。这使开发人员能够以非侵入性但有用且一致的方式来记录红宝石方法和参数的类型签名。代替在说明书正文中描述此数据，开发人员可以在一行中正式声明参数或返回类型。考虑以下以YARD格式记录的方法：

# Reverses the contents of a String or IO object.
#
# @param contents [String, #read] the contents to reverse
# @return [String] the contents reversed lexically
def reverse(contents)
  contents = contents.read if contents.respond_to? :read
  contents.reverse
end

通过上面的@param标记，我们了解到content参数可以是String或响应“ read”方法的任何对象，这比文本描述（其应为IO对象）更强大。这也通知开发人员，他们应该期望收到该方法返回的String对象，尽管这对于“反向”方法可能是显而易见的，但是当方法名称可能不具有描述性时，它将变得非常有用。

3. YARD的自定义构造和可扩展性：YARD旨在通过插件进行扩展和定制。以需要记录以下代码的场景为例：

class List
 # Sets the publisher name for the list.
 cattr_accessor :publisher
end

此自定义声明提供了动态生成的代码，文档工具很难在没有开发人员帮助的情况下正确地编写代码。为了减轻手动记录过程的麻烦，开发人员可以扩展YARD来处理cattr_accessor构造，并使用相关的文档自动在类上创建属性。这使得记录外部API（尤其是动态API）对于用户的使用而言更加一致。

YARD还为其他任何地方的可扩展性而设计，使您可以添加对新编程语言，新数据结构甚至数据存储位置/方式的支持。

4.原始数据输出：YARD还可以将记录的对象作为原始数据（转储的命名空间）输出，可以在以后重新加载以进行生成，甚至审计代码。这意味着任何开发人员都可以使用原始数据为任何自定义格式（例如YAML）执行输出生成。尽管YARD计划支持XHTML样式的文档输出以及命令行（基于文本）和可能的XML，但对于希望从其他形式获得YARD处理优势的人（例如将所有文档都扔进去），这可能仍然有用。数据库。利用这种原始数据格式的另一种有用方法是编写可以自动生成测试用例的工具，或者在代码中显示可能未处理的异常。

5.本地文档服务器：YARD可以为项目或已安装的gem（类似于gem server）提供文档，并具有动态搜索和实时重新加载的附加优势。使用实时重新加载功能，您可以记录代码并通过刷新页面立即预览结果；YARD将完成重新生成HTML的所有工作。这使编写文档变得更快。