BT

如何利用碎片时间提升技术认知与能力? 点击获取答案

YARD──Ruby代码元数据和文档生成器

| 作者 Werner Schuster 关注 9 他的粉丝 ,译者 李明(nasi) 关注 0 他的粉丝 发布于 2008年8月4日. 估计阅读时间: 4 分钟 | QCon上海2018 关注大数据平台技术选型、搭建、系统迁移和优化的经验。
Merb的贡献者、EngineYard的雇员Yehuda KatzRubyFringe的演讲中,提到了一些接下来要关注的工具。其中之一就是文档生成工具YARD,它支持为Ruby文档添加元数据,并且还有一些其他的特性。Yard对 RDoc格式化文档字符串支持的很好,而且还允许用户使用其他的标记符号。YARD可扩展,允许用户编写自定义处理插件,可以用于代码生成或者支持不同的输出后端。

显著的特性之一便是对注释字符串中元数据的支持。对于那些习惯Javadoc的使用者来说,这种元标签符号并不陌生(取自于YARD的Readme):
# 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 respond_to? :read
 contents.reverse
end

contents参数展示了如何为方法参数添加类型提示。这个参数可以是一个String,也可以是任何带有#read方法的类(InfoQ曾经探讨过动态类型和协议中类型注释的不同方法)。

RDoc 2.1和YARD都提供了为元编程方法编写文档的方法。使用RDoc,一段以“##”开头的注释就定义了该注释是为一个元编程方法所编写的。它启发式地忽略掉紧邻的标识符,并把接下来的符号作为方法名:
## 
# Does stuff.
add_method :foo

如果方法并没有实际在源代码中出现,但是却作为类接口的一部分的话,可以这样来为其编写文档:

##
# :method invisible_method

YARD使用可扩展Handler构建。事实上,最基本的核心就是用Handler来实现的。新Handler可以通过扩展YARD::Handlers::Base类来添加,并覆写process类即可。这使得用户可以为自定义结构编写handler,例如内部DSL或者类似RDoc的处理行为。

在一个项目上使用YARD需要创建一个.yardoc数据库,把所有收集到的代码结构和数据缓存起来。YARD的yri工具,就像ri那 样,通过这个数据来做到交互式文档查询。YARD也可以将缓存在数据库中的信息以多种格式输出,而不需要重复的分析。YARD的缓存和IDE创建的代码索 引很相似,可以允许高级代码搜索(例如,搜索语言构成,而不仅仅是全文检索)、代码浏览,或者为那些需要关注工程中全部代码的重构工具的使用带来便利。

这种为方法在注释中提供元数据的主意在Ruby界已经由来已久。一些项目已经在注释中引入了可选类型注释。例如Merb的文档指南中写到
所有的方法(公用的或者私有的)都必须提供一个清晰的方法署名,包括所有参数的类型、可选Hash的可能取值,以及返回类型和其他信息等等。
Merb目前采用了一种不同的符号标记来做方法署名。

SapphireSteel的Ruby In Steel IDE也提供了另外一种方法:Type Assertions。它所采用的元数据和Javadoc的@tag以及YARD所使用的格式不同,主要是用于文档和协助IntelliSense(展示Type Assertions如何协助IntelliSence的视频)。

评价本文

专业度
风格

您好,朋友!

您需要 注册一个InfoQ账号 或者 才能进行评论。在您完成注册后还需要进行一些设置。

获得来自InfoQ的更多体验。

告诉我们您的想法

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我
社区评论

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

允许的HTML标签: a,b,br,blockquote,i,li,pre,u,ul,p

当有人回复此评论时请E-mail通知我

讨论

登陆InfoQ,与你最关心的话题互动。


找回密码....

Follow

关注你最喜爱的话题和作者

快速浏览网站内你所感兴趣话题的精选内容。

Like

内容自由定制

选择想要阅读的主题和喜爱的作者定制自己的新闻源。

Notifications

获取更新

设置通知机制以获取内容更新对您而言是否重要

BT