很多时候我们想知道一个gem怎么用，就得去查他的文档，然而大部分文档都是纯英文，对于英文水平一般的人来说，最多只能去找这个方法怎么用，命令行里怎么写，提供的方法是怎么样的。。。。。。等一些基本信息，然而作者的心得，注释什么的就会被忽略，于是我用谷歌翻译花了点时间翻译了一下，顺便对比使用了百度翻译和有道词典，最后还是谷歌翻译翻译这种技术类文档的比较专业
YARD文档 翻译：peter
YARD是一个文档生成工具Ruby编程语言。它使用户能够生成一致的，可使用的文件，可以很容易导出为多种格式，同时还支持自定义扩展的Ruby构建，如自定义类级别定义。下面是一些YARD的显着特点的总结。
1.的RDoc/ SimpleMarkup格式兼容性：YARD被制成具有的RDoc格式兼容。实际上，堆场确实上的RDoc文档字符串没有处理，并且离开该到输出生成工具来决定如何呈现的文档。
2. Yardoc元标记格式如Python，Java和Objective-C和其他语言：YARD用来旁边常规代码文档的元标记一个“@tag”样式定义的语法。这些标记应该能够快乐地并肩而坐的RDoc格式的文档，但提供一个更加一致的和可用的方法来描述有关对象，如什么参数，他们需要什么类型的他们预计，重要的信息是什么类型的方法应该返回，有什么异常就可以提高，如果它已被弃用，等等。这也让信息更好（更一致）在输出生成阶段组织。你可以找到的标签在Tags.md文件列表。
YARD还支持可选的“类型”声明的某些标记。这使得开发人员文档类型签名ruby的方法和参数，以非侵入性，但有用的，一致的方式。相反，描述说明体内这些数据，开发者可以正式宣布在一行中的参数或者返回类型（S）。考虑记录与YARD格式下面的方法：
# Reverses the contents of a String or IO object.
#
# @param [String, #read] contents 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标签，我们知道的内容的参数可以是一个字符串或响应该“读”的方法，这是比文字说明，这表示，它应该是一个IO对象更强大的任何对象。这也通知他们应当期望接收该方法返回字符串对象的显影剂，尽管这可能是明显的“反向”方法，它当方法名称可能不那么描述性变得非常有用。
3.自定义构造和院子的可扩展性：YARD旨在扩展和插件定制。就拿你需要记录下面的代码的情况：
class List
# Sets the publisher name for the list.
cattr_accessor :publisher
end
这报关提供动态生成的代码，是很难的文档，工具，未经开发商帮助正确记录。为了缓解手工记录的过程中的阵痛，YARD可以由开发扩展到处理cattr_accessor结构，并自动创建的类中的属性与相关文档。这使得记录外部API的，特别是动态的，有很多供用户消费更加一致。
Yard 还设计了可扩展其他地方一样，允许您添加支持新的编程语言，新的数据结构，甚至在那里/数据存储方式。
4.原始数据输出：YARD也输出文档对象作为原始数据（倾销命名空间），可以重新装载做代在稍后的日期，甚至是审计的代码。这意味着，任何开发人员可以使用原始数据进行输出生成的任何定制格式，如YAML，例如。虽然YARD计划支持XHTML风格的文档输出，以及命令行（基于文本），并可能XML，这可能仍然是为那些谁愿意获得YARD的处理带来的好处其他形式，如投掷所有的文档转换成有用一个数据库。利用这种原始数据格式的另一种有用的方法是将写工具，可以自动生成测试情况下，例如，或显示在代码可能未处理的异常。
5.本地文件服务器：YARD可以为文档，项目或安装的gems（类似于 gem server）与动态搜索的好处，以及现场重新加载。使用实时重装功能，可以记录你的代码，并立即通过刷新页面预览结果; YARD将做重新生成HTML的所有工作。这使得写文档更加快速的过程。
安装
要安装YARD，请使用以下命令：
$ gem install yard
或者，如果你已经出直接检查源代码，你可以调用从根项目目录耙安装。
为Debian/ Ubuntu用户重要提示：有一个可能的机会，你的Ruby安装缺少的RDoc，这是偶尔使用子里标记转换为HTML。如果运行的RDOC变成了空，发出安装的RDoc：
$ sudo apt-get install rdoc
用法
这里有两种方式来使用YARD。第一种是通过命令行，第二个是Rake任务。
1 命令行
YARD封装了许多功能，包括生成文档，图表运行YARD服务器，等一个可执行文件命名的yard。要查看可用YARD命令，类型的列表：
$ yard —help
插件还可以添加命令到yard可执行文件以提供额外的功能。
生成文档
该yardoc可执行文件是yard文档的快捷方式。
你可能会使用最常见的命令是yard的文档，或yardoc。您可以键入yardoc--help看到YARD提供的选项，但最简单的方法来生成文档为您的代码是简单地键入yardoc在你的项目的根。这将假设你的文件位于lib /目录。如果它们位于其他位置，您可以通过命令行指定路径：
$ yardoc 'lib/**/*.rb' 'app/**/*.rb' …etc…
该工具会生成一个将存储您的源代码和文档缓存数据库.yardoc文件。如果要重新生成您的文档与另一模板，你可以简单地使用—use缓存（或-c）选项加速跳过源解析生成过程。
YARD在默认情况下只在您的公开可见性文件的代码。您可以通过添加—protected或--private的选项开关记录您的protected和private代码。此外，您可以添加--no私有的，也忽视具有@private元标记的任何对象。这类似于的RDoc的“：nodoc：”行为，虽然区别是重要的。的RDoc意味着与对象：nodoc：不会被记录，而YARD仍然建议记录的私有API的私人对象（维护/开发者的消费）。
您也可以通过分离和匹配替换文件名添加额外的信息文件（README，LICENSE）“ - ”。
$ yardoc 'app/**/*.rb' - README LICENSE FAQ
如果没有匹配替换先于' - '参数，默认的的glob（LIB/**/* RB）时：
$ yardoc - README LICENSE FAQ
请注意，README文件可以有自己的—readme开关来指定。
您还可以.yardopts文件添加到您的项目目录，其中列出由空格（换行或空格）分隔开的开关传递给yardoc只要运行。该.yardopts文件的全面概述可以在YARD:: CLI:: Yardoc被发现。
查询
该yardoc工具还支持—query参数仅包括符合特定的数据或元数据查询的对象。查询语法是Ruby的，但也有一些快捷键可用。例如，记录只有那些与价值“公共”的“@api”标签的对象，下面所有的语法都会给出相同的结果：
--query '@api.text == "public"'
--query 'object.has_tag?(:api) && object.tag(:api).text == "public"'
--query 'has_tag?(:api) && tag(:api).text == “public"'
有关查询语法的详细信息，请参阅 YARD::Verifier class。
2. rake任务
第二个最明显的是产生通过Rake任务文档。您可以通过添加以下到您的Rake文件做到这一点：
YARD::Rake::YardocTask.new do |t|
t.files = ['lib/**/*.rb', OTHER_PATHS] # optional
t.options = ['--any', '--extra', '--opts'] # optional
t.stats_options = ['--list-undoc'] # optional
end
所有设置：文件，选项和stats_options是可选的。文件将默认为lib/**/ *。RB，选择会代表你可能要添加的stats_options将通过额外的选项给stats命令的任何选项。此外，可通过输入yardoc—help在shell的选项的完整列表。您也可以覆盖这些选项在与OPTS环境变量rake命令行：
$ rake yard OPTS='--any --extra —opts'
3. YRI RI实施
该YRI二进制将使用缓存的.yardoc数据库，让您快速地里式访问您的文件。它的方式比里更快，但目前并没有与STDLIB或核心Ruby库，仅在活动项目的工作。示例：
$ yri YARD::Handlers::Base#register
$ yri File.relative_path
需要注意的是类方法不能被称为与“::”命名空间分隔。只有模块，类和常量应使用“::”。
您也可以在任何安装了gems里查找。只要确保建立.yardoc数据库的安装gem搭配：
$ sudo yard gems
如果您没有用sudo访问，将这些文件写入到〜/.yard目录。 YRI也将缓存查找存在。
4.yard服务 - 文档服务器
yard server命令用来为本地项目或所有已安装的RubyGems的文档。以服务为你工作在一个项目文档，只需运行：
$ yard server
而当前目录中的项目将被解析（如果源还未被扫描YARD），并提供在http://localhost:8808.
重加载
如果你想为文档的一个项目，而你将其记录下来，以便您可以预览结果，简单地传递—reload（-r），以上面的命令和庭院将重新加载在每个请求的任何更改的文件。这将允许你改变任何文件的来源，并刷新才能看到新的内容。
Serving Gems
服务为所有已安装的gem文档，使用：
$ yard server —gems
这也将自动为先前没有被扫描的任何gem建文档。注意，在这种情况下，将有一个新解析GEM的第一请求之间有轻微的延迟。
5. yard graph Graphviz Generator
您可以使用yard图形生成的代码点的图表。这当然，需要的Graphviz和点二进制。默认情况下，这将产生在Graphviz的可支持的最佳UML2符号类和模块的图形，但没有任何方法列出。随着—full选项，方法和属性将陆续上市。还有一个--dependencies选项来显示混入杂质。您可以输出到标准输出或文件，或管道直接点。同样的公共，保护和私有可视性规则适用于堆场图。更多选项可以通过输入码的图--help待观察，但这里有一个例子：
$ yard graph --protected --full —dependencies
网友评论