8000 GitHub - Bodacious/yard: YARD is a Ruby Documentation tool. The Y stands for "Yay!"
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Bodacious/yard

BranchesTags
 
 

Repository files navigation

YARD: Yay! A Ruby Documentation Tool

Homepage GitHub Documentation Gitter Chat

Gem Version Build Status License

Synopsis

YARD is a documentation generation tool for the Ruby programming language. It enables the user to generate consistent, usable documentation that can be exported to a number of formats very easily, and also supports extending for custom Ruby constructs such as custom class level definitions. Below is a summary of some of YARD's notable features.

Feature List

1. RDoc/SimpleMarkup Formatting Compatibility: YARD is made to be compatible with RDoc formatting. In fact, YARD does no processing on RDoc documentation strings, and leaves this up to the output generation tool to decide how to render the documentation.

2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other languages: YARD uses a '@tag' style definition syntax for meta tags alongside regular code documentation. These tags should be able to happily sit side by side RDoc formatted documentation, but provide a much more consistent and usable way to describe important information about objects, such as what parameters they take and what types they are expected to be, what type a method should return, what exceptions it can raise, if it is deprecated, etc.. It also allows information to be better (and more consistently) organized during the output generation phase. You can find a list of tags in the {file:docs/Tags.md#taglist Tags.md} file.

YARD also supports an optional "types" declarations for certain tags. This allows the developer to document type signatures for ruby methods and parameters in a non intrusive but helpful and consistent manner. Instead of describing this data in the body of the description, a developer may formally declare the parameter or return type(s) in a single line. Consider the following method documented with YARD formatting:

 # 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

With the above @param tag, we learn that the contents parameter can either be a String or any object that responds to the 'read' method, which is more powerful than the textual description, which says it should be an IO object. This also informs the developer that they should expect to receive a String object returned by the method, and although this may be obvious for a 'reverse' method, it becomes very useful when the method name may not be as descriptive.

3. Custom Constructs and Extensibility of YARD: YARD is designed to be extended and customized by plugins. Take for instance the scenario where you need to document the following code:

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

This custom declaration provides dynamically generated code that is hard for a documentation tool to properly document without help from the developer. To ease the pains of manually documenting the procedure, YARD can be extended by the developer to handle the cattr_accessor construct and automatically create an attribute on the class with the associated documentation. This makes documenting external API's, especially dynamic ones, a lot more consistent for consumption by the users.

YARD is also designed for extensibility everywhere else, allowing you to add support for new programming languages, new data structures and even where/how data is stored.

4. Raw Data Output: YARD also outputs documented objects as raw data (the dumped Namespace) which can be reloaded to do generation at a later date, or even auditing on code. This means that any developer can use the raw data to perform output generation for any custom format, such as YAML, for instance. While YARD plans to support XHTML style documentation output as well as command line (text based) and possibly XML, this may still be useful for those who would like to reap the benefits of YARD's processing in other forms, such as throwing all the documentation into a database. Another useful way of exploiting this raw data format would be to write tools that can auto generate test cases, for example, or show possible unhandled exceptions in code.

5. Local Documentation Server: YARD can serve documentation for projects or installed gems (similar to gem server) with the added benefit of dynamic searching, as well as live reloading. Using the live reload feature, you can document your code and immediately preview the results by refreshing the page; YARD will do all the work in re-generating the HTML. This makes writing documentation a much faster process.

Installing

To install YARD, use the following command:

$ gem install yard

(Add sudo if you're installing under a POSIX system as root)

Alternatively, if you've checked the source out directly, you can call rake install from the root project directory.

Important Note for Debian/Ubuntu users: there's a possible chance your Ruby install lacks RDoc, which is occasionally used by YARD to convert markup to HTML. If running which rdoc turns up empty, install RDoc by issuing:

$ sudo apt-get install rdoc

Usage