应用JSF、Ajax和Seam开发Portlets（1/3）
.gif)
本文主要讲述了如何用JBoss Portlet Container 和JBoss Portlet Bridge创建新项目，怎样配置一个JSF应用去使用JBoss Portlet Bridge，以及JBoss Portlet Bridge所具备的功能。
新闻
YARD──Ruby代码元数据和文档生成器
作者 Werner Schuster译者 李明（nasi） 发布于 2008年8月2日 下午10时41分
Merb的贡献者、EngineYard的雇员Yehuda Katz在RubyFringe的演讲中，提到了一些接下来要关注的工具。其中之一就是文档生成工具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的视频）。
没有回复
回复