One distinguishing feature is the support for metadata in comment strings. Users of tools like Javadoc will find the meta tag notation familiar (from the 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
The
contents
parameter shows how to add type hints to the method argument. The argument can either be a String
, or any class with a #read
method (InfoQ previously discussed different approaches to type annotations in relation to protocols and duck typing). Both RDoc 2.1 and YARD provide ways to document metaprogrammed methods. With RDoc, a comment starting with "##" defines a comment for a metaprogrammed method. The heuristic is to ignore the identifier immediately following the comment and take the following token as the method name:
##
# Does stuff.
add_method :foo
Methods that don't actually appear in the source code, but are part of the class interface can be documented like this:
##
# :method invisible_method
YARD is built with pluggable handlers - in fact, the basic functionality is implemented as handlers. A new handler can be added by extending the
YARD::Handlers::Base
class, and overriding the process
class, which allows to write handlers for custom constructs, such as internal DSLs or behavior similar to RDoc's solutions.Running YARD on a project creates a
.yardoc
database which caches the gathered code structure and data. YARD's yri
tool, which works like ri
and uses this database to allow for interactive documentation lookup. YARD can also use the cached information in the database to generate output in multiple formats, without having to analyze the repeatedly. YARD's cache is similar to code indexes created by IDEs to allow for advanced code search (i.e. searching for language constructs, not just fulltext search), code browsing, or for refactoring tools that need to be aware of all code in a project. The idea to provide metadata about methods in comments has been around for some time in the Ruby space. Some projects promote optional type annotations in comments. Merb, for instance, has the following documentation guideline:
All methods (public and private) are required to provide a clear method signature, including the types for any parameters, and the possible values for any options hashes, as well as return types and other information.Merb currently uses a different notation to specify the method signature.
Another approach is supported in SapphireSteel's Ruby In Steel IDE: Type Assertions The metadata uses a different format than the
@tag
of Javadoc or YARD, but it's indexed and used for documentation and to help IntelliSense (Screencast describing how to help IntelliSense with Type Assertions).
Community comments
Change the language, not the documentation style
by Daniel Berger,
Change the language, not the documentation style
by Daniel Berger,
Your message is awaiting moderation. Thank you for participating in the discussion.
One of things that I talked with Charles Nutter about on #jruby is that, if you allowed optional typing and method annotations in the language itself, document generators could use that information instead of forcing authors to adopt a particular documentation style.
For example, let's say we implement some form of Duby, with annotations to boot. You'll end up with something like this:
Meaning contents is a String, and the method returns a String. In addition to making it easier for document generators, it provides additional, inspectible metadata for that method.
Note that I'm not even suggesting that the argument type be enforced. It could be strictly for document generation, or it could merely emit a warning or whatever we want it to do.