yard

# YARD: Yay! A Ruby Documentation Tool

[![Homepage](https://img.shields.io/badge/home-yardoc.org-blue.svg)](https://yardoc.org)
[![GitHub](https://img.shields.io/badge/github-lsegal/yard-blue.svg)](https://github.com/lsegal/yard)
[![Documentation](https://img.shields.io/badge/docs-rdoc.info-blue.svg)](https://rubydoc.org/gems/yard/frames)

[![Gem Version](https://badge.fury.io/rb/yard.svg)](https://github.com/lsegal/yard/releases)
[![Unit Tests](https://github.com/lsegal/yard/actions/workflows/ci.yml/badge.svg)](https://github.com/lsegal/yard/actions/workflows/ci.yml)
[![Coverage Status](https://coveralls.io/repos/github/lsegal/yard/badge.svg)](https://coveralls.io/github/lsegal/yard)
[![License](https://img.shields.io/badge/license-MIT-yellowgreen.svg)](#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. Builtin RDoc/Markdown Hybrid Support**: YARD ships with a builtin markup
renderer that supports both RDoc and Markdown formatting out of the box—no
external gem required. You can freely mix RDoc-style and Markdown-style
documentation without installing any additional libraries.

**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:

```ruby
# Reverses the contents of a String or IO object.
#
# @param contents [String, #read] 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