What's New in 0.8.x?

Directives (new behavioural tag syntax) (0.8.0)
Added --embed-mixin(s) to embed mixins into class docs (0.8.0)
Internationalization (I18n) support for translating docs (0.8.0)
New C parser / handlers architecture (0.8.0)
YARD will now warn if @param name not in method params (0.8.0)
Added support for module_function calls in Ruby code (0.8.0)
Greatly improved tag documentation using custom template (0.8.0)
Tags can now contain '.' for namespacing (0.8.0)
Added "frames" links for non-framed pages for better nav (0.8.0)
Added Gemfile support to YARD server for local gem sets (0.8.0)
Server now displays README on index route like static docs (0.8.0)
Added line numbers to yard stats --list-undoc --compact (0.8.0)
Single object db now default (multi-object db unsupported) (0.8.0)
Added --api tag to generate documentation for API sets (0.8.1)
Added --non-transitive-tag to disable transitive tag (0.8.3)
Added -B/--bind to bind to a port in yard server (0.8.4)
Added asciidoc markup type support (0.8.6)
Added yard markups command to list available markup types (0.8.6)
Added yard display command to display formatted objects (0.8.6)
Added --layout to yard display command (0.8.6.1)
Added stats_options for the rake task (0.8.7.6)

Directives (new behavioural tag syntax) (0.8.0)

The tags @!macro, @!method, @!attribute, @!group, @!endgroup, @!scope and @!visibility have been changed from meta-data tags to directives. This means they should now be called with the "@!" prefix instead of "@". Note however that for backward compatibility, the old "@macro", "@method", etc., syntax for all of these tags will still work and is supported.

Some backwards incompatible changes were made to @!macro syntax. Please read this section carefully if you are using this tag.

YARD 0.8.0 adds a new tag syntax called "directives" using the @! prefix. These directive tags can be used to modify parser state while processing objects, or even create new objects on the fly. A plugin API is available similar to tags, and directives should be registered in the YARD::Tags::Library class using YARD::Tags::Library.define_directive.

To use a directive, simply call it the same way as any tag. Tag syntax is documented in Tags.

Notable features of directives

Directives do not need to be attached to object docstrings

Unlike meta-data tags which apply to created objects, directives do not need to be attached to an object in order to be used. This means you can have free-standing comments with directives, such as:

# @macro mymacro
#   A new macro, not attached to any docstring

# ...other Ruby code here...

# Using the macro:
# @macro mymacro
def mymethod; end

You can do the same to define methods and attributes, as discussed below.

`@!method` and `@!attribute` directives improved

The method and attribute directives can now be used to create multiple objects in a single docstring. Previously a @method or @attribute tag would only create one method per docstring. In 0.8.0, you could attach multiple methods to the same block of Ruby source, such as:

# @!method foo(a, b, c)
# @!method bar(x, y, z)
# Docstring for code
some_ruby_source

The above creates #foo and #bar and the source listing for both will be some_ruby_source with "Docstring for code" as the docstring.

The attribute directive can take advantage of this functionality as well. Note that these directives also do not need to be attached to a line of code to be recognized; they can be in free-standing comments if the methods are defined dynamically and not associated with any code.

New `@!parse` directive to parse Ruby code

A new @!parse directive was added that allows a developer to have YARD parse code that might not necessarily be parsable in its original form. This is useful when using instance_eval and other dynamic meta-programming techniques to define methods or perform functionality. For instance, a common case of the "self.included" callback in module to extend a module on a class might be in the form:

def self.included(mod)
  mod.extend(self)
end

Unfortunately, this does not get picked up by YARD, but on the original class, we can add:

class MyClass
  # @!parse extend TheDynamicModule
  include TheDynamicModule
end

YARD will then parse the code extend TheDynamicModule as if it were in the source file.

You can also use this technique to register regular methods as attributes, if you did not define them with attr_* methods:

def foo; @foo end
def foo=(v) @foo = v end

# Register them as methods:
# @!parse attr_accessor :foo

Backward incompatible changes to `@!macro` directive

Unfortunately, in order to create the new directives architecture, some previously supported syntax in @macro tags are no longer supported. Specifically, macros can no longer expand text on an entire docstring. Instead, macros only expand the data that is indented inside of the tag text.

This syntax is no longer supported:

# @macro mymacro
# Expanding text $1 $2 $3
property :a, :b, :c

In 0.7.0 to 0.7.5, the above would have created a method with the docstring "Expanding text a b c". This will not work in 0.8.0. Instead, you must indent all the macro expansion data so that it is part of the @macro tag as follows:

# @!macro mymacro
#   Expanding text $1 $2 $3
property :a, :b, :c

Note that we also use the recommended @!macro syntax, though @macro is still supported.

Added `--embed-mixin(s)` to embed mixins into class docs (0.8.0)

Methods from mixins can now be embedded directly into the documentation output for a class by using --embed-mixin ModuleName, or --embed-mixins for all mixins. This enables a documentation writer to refactor methods into modules without worrying about them showing up in separate files in generated documentation. When mixin methods are embedded, they show up in both the original module page and the pages of the classes they are mixed into. A note is added to the method signature telling the user where the method comes from.

The --embed-mixin command-line option can also take wildcard values in order to match specific namespaces. For instance, you can embed only mixins inside of a "Foo::Bar" namespace by doing:

$ yard doc --embed-mixin "Foo::Bar::*"

Internationalization (I18n) support for translating docs

YARD now ships with the beginnings of internationalization support for translating documentation into multiple languages. The yard i18n command now allows you to generate ".pot" and ultimately ".po" files for translation with gettext.

Note that this tool is a small step in the larger transition for proper I18n support in YARD. We still have to add proper gettext support to our templates for proper generation in multiple languages, but this tool allows you to get started in translating your documents. Improved I18n support will come throughout the 0.8.x series.

New C parser / handlers architecture (0.8.0)

The C parser was completely rewritten to take advantage of YARD's parser and handler architecture. This means more YARD will be more robust when parsing failures occur, tags and directives will now work consistently across Ruby and CRuby files (@!group will now work, for instance), and developers can now write custom handlers that target CRuby source files.

YARD will now warn if `@param` name not in method params (0.8.0)

YARD will now give you a warning if you use a @param tag in your source but give an invalid parameter name. This should catch a lot of common documentation errors and help keep your documentation consistent.

Added support for `module_function` calls in Ruby code (0.8.0)

The module_function command in Ruby is now supported in Ruby files. It defines two separate methods, one class and one instance method, both having the exact same docstring, and marks the instance method as private.

Greatly improved tag documentation using custom template (0.8.0)

We have completely revamped the docs/Tagsdocs/Tags.md to include documentation for each meta-data tag and directive with at least one useful example for each one. This was done using template customization and extension available within YARD.

Tags can now contain '.' for namespacing (0.8.0)

Prior to 0.8.0, tags could only contain alphanumeric characters and underscore. YARD now allows the '.' character in tag names, and it is now recommended for namespacing project-specific custom tags. YARD has its own set of custom tags that are namespaced in this way (using the "yard.tagname" namespace). The namespace recommendation is to use "projectname.tagname", or "projectname.component.tagname".

Added "frames" links for non-framed pages for better nav (0.8.0)

Frames navigation has always had a "(no frames)" link to get rid of the frameset. YARD 0.8.0 introduces a "(frames)" link on non-framed pages to reverse this, allowing you to navigate between framed and frameless pages seamlessly.

Added Gemfile support to YARD server for local gem sets (0.8.0)

The yard server command now supports --gemfile to serve gems from a Gemfile.lock, instead of all system-wide gems.

Server now displays README on index route like static docs (0.8.0)

The yard server command will now behave like static docs regarding the index action for a project, listing the README file if present before displaying the alphabetic index. Note that the route for the alphabetic index page has now moved to the explicit '/index' action.

Added line numbers to `yard stats --list-undoc --compact` (0.8.0)

Line numbers are now listed in the compact listing of undocumented objects so that they can be more easily located in the files.

Single object db now default (multi-object db unsupported) (0.8.0)

YARD previously would split the .yardoc db into multiple marshal files for load-time performance reasons if it grew past a specific number of objects. This check is now disabled, and YARD will never automatically switch to a multi-object DB. YARD will now always use the single object db unless explicitly set with --no-single-db. If YARD is taking a long time to load your .yardoc database, you can try using this option to split your database into multiple files, but note that this can cause problems with certain codebases (specifically, if you have class methods using the same name as a module/class).

Added `--api` tag to generate documentation for API sets (0.8.1)

You can now use yardoc --api APINAME to generate documentation only for objects with the @api APINAME tag (or any parent namespace objects, since this tag is transitive). Multiple --api switches may be used to generate documentation for multiple APIs together. The following generates documentation for both the "public" and "developer" APIs, also including any objects with undefined API (via --no-api):

$ yard doc --api public --api developer --no-api

Note that if you use --api, you must ensure that you also add @api tags to your namespace objects (modules and classes), not just your methods. If you do not want to do this, you can also include all objects with no @api tag by using --no-api as shown above.

Remember that applying an @api tag to a class or module will apply it to all children that do not have this tag already defined, so you can declare an entire class public by applying it to the class itself. Note also that these tags can be overridden by child elements if the tag is re-applied to the individual object.

This feature is a simplified version of the more powerful --query switch. The query to display the same API documentation as the above example would be:

$ yard doc --query '!@api || @api.text =~ /^(public|private)$/'

But note that --query does not work when YARD is in "safe mode" due to security concerns, whereas --api works in either mode. This enables --api to function on remote documentation sites like rubydoc.info.

Added `--non-transitive-tag` to disable transitive tag (0.8.3)

You can now use --non-transitive-tag to disable transitivity on tags that are defined as transitive by default. For instance, in some cases you might not want the @api tag to apply to all methods when you define it on a class. Only the class itself has a specific @api tag. To do this, you can mark @api as non-transitive with:

$ yard doc --non-transitive-tag api --api some_api

Which will avoid classifying treating @api as a transitive tag when parsing modules and classes.

Added `-B/--bind` to bind to a port in yard server (0.8.4)

You can now bind the yard server command to a given local port with yard server -B PORT or yard server --bind PORT.

Added `asciidoc` markup type support (0.8.6)

Support for the AsciiDoc markup type is now introduced using the asciidoc markup type (yard doc -m asciidoc). Requires the asciidoctor RubyGem library to be installed before running YARD.

Added `yard markups` command to list available markup types (0.8.6)

You can now list all available markup types and their respective providers by typing yard markups. This list also includes the file extensions used to auto-identify markup types for extra files and READMEs. To use a markup in the list, call yard doc with -m MARKUP_TYPE. To select a specific markup provider library, pass the -M PROVIDER_NAME option.

Added `yard display` command to display formatted objects (0.8.6)

This feature requires the .yardoc registry to have already been generated. To generate the registry, run yard doc -n.

You can now display a single object (or a list of objects) in the YARD registry using the yard display OBJECT ... command. For example, to display the YARD::CodeObjects module as text (the way it is displayed in yri), type:

$ yard display YARD::CodeObjects

You can also format individual objects as HTML. For example, you can format the above object as HTML and pipe the contents into a file readable by a web browser:

$ yard display -f html YARD::CodeObjects > codeobjects.html

Custom templating options from yard doc can also be used, see yard display --help for more options.

Added `--layout` to `yard display` command (0.8.6.1)

The yard display command now accepts --layout to wrap content in a layout template. Currently the layout and onefile layout templates are supported, though any template can be used. If no parameter is specified, the layout will default to the layout template. Example usage:

$ yard display --layout onefile -f html YARD::CodeObjects > codeobjects.html

The above generates a codeobjects.html file that is self-contained with CSS stylesheets and JavaScript code. This is similar to calling yard doc --one-file with only the YARD::CodeObjects object in the registry.

Note that even though this uses the onefile template, the README file will not be auto-included the way it is with the yard doc command. To include the README text at the top of the onefile template, pass the --readme switch:

$ yard display --layout onefile -f html --readme README.md OBJECT > out.html

What's New in 0.7.x?

Macro support and detection of DSL methods (0.7.0)
Inherited attributes now show in HTML output (0.7.0)
The 'app' directory is now parsed by default (0.7.0)
Added support for metadata (@title, @markup) in extra files/readmes (0.7.0)
Added yard list command (alias for yardoc --list) (0.7.0)
Added Git support in yard diff (0.7.0)
Added {include:file:FILENAME} syntax (0.7.0)
Added {render:OBJECT} syntax to embed object docs in extra files (0.7.0)
Added improved templates API for custom CSS/JS/menus (0.7.0)
Added Ruby markup type (-m ruby) (0.7.0)
Added state tracking variables to Parser/Handler architecture (0.7.0)
Added before/after callbacks to SourceParser (0.7.0)
Can now use --yardopts FILE to specify a custom yardopts file (0.7.0)
Added new -t guide template for guide based docs (0.7.0)
Github Flavoured Markdown now works out-of-box (0.7.4)
Added -m textile_strict and -m pre markup types (0.7.4)
Reorganized markup types 'text' and 'none' (0.7.4)
Add support for rb_define_alias (0.7.4)

Macro support and detection of DSL methods (0.7.0)

YARD will now automatically detect class level method calls, similar to the way it knows what an attr_accessor is. By simply adding documentation to your class level declarations, YARD can automatically detect them as methods or attributes in your class. Consider DataMapper's "property" declaration:

class Post
  # @attribute
  # @return [String] the title of the post
  property :title, String
end

The above declaration would be created as the Post#title. The optional @attribute tag tells YARD that the property is an "attribute", and not just a regular method.

In addition to basic DSL method detection, YARD also supports macros to create docstrings that can be copies to other objects; these macros can also be "attached" to class level methods to create implicit documentation for macros.

Macros and DSL method detection are discussed in much more detail in the GettingStarted, so you should read about them there if you're interested in this feature.

Inherited attributes now show in HTML output (0.7.0)

Inherited attributes will now show up in HTML documentation using the default template in the same manner that inherited methods do.

The 'app' directory is now parsed by default (0.7.0)

YARD tries to follow the "It Just Works" attitude in writing developer tools, and therefore has added app/**/*.rb to the default list of globs that it searches for code in. You no longer need to create a .yardopts just to list your app directory when documenting your code on rubydoc.info. We should have done this a while ago! And don't worry, YARD still checks lib and ext by default, too.

Added support for metadata (@title, @markup) in extra files/readmes (0.7.0)

Extra files (READMEs, ChangeLogs, LICENSE files, and other guides) now support metadata tags, just like docstrings in code comments. By adding @tag values to the top of a file (no whitespace preceding it) inside of a # comment line, YARD will detect and parse these tags and store it for later usage.

Tags can contain arbitrary data as well as arbitrary tag names, however the tag names @title and @markup are reserved to specify the document title and markup format respectively. The title will be used in the file list menu, index page, as well as any linking of the file via the {file:Filename} syntax. An example of a document with metadata would be:

# @title The Best Project Ever!
# @markup rdoc
# @author Foo Bar (custom tag, does not display in templates)

= This Project Rules

== Contents

...

Note that previous versions of YARD recommended specifying the markup of an extra file with the #!markup shebang, but the @markup metadata tag is now the "best practice" for specifying the markup format of an extra file.

Added `yard list` command (alias for `yardoc --list`) (0.7.0)

The yardoc --list command is used to list objects that are parsed from a codebase. This can be used to grep methods/classes in a codebase from the command line. yard list now calls yardoc --list as a convenience command.

Note that the yardoc --list command may eventually be replaced by a more feature-filled yard list command, so yard list should be used instead of yardoc --list when possible.

Added Git support in `yard diff` (0.7.0)

The yard diff command can now perform object diffing on git repositories. Provide the --git switch to yard diff with 2 commit/branches like so:

$ yard diff --git HEAD~5 HEAD
Added objects:

  YARD::Parser::SourceParser#contents
  YARD::Parser::SourceParser#globals
  ...

Added `{include:file:FILENAME}` syntax (0.7.0)

You can now use the {include:file:FILENAME} syntax to embed the contents of an extra file marked up in its markup format. This syntax supports embedding Ruby source files and performing syntax highlighting on the code.

Added `{render:OBJECT}` syntax to embed object docs in extra files (0.7.0)

You can now use the {render:Object} syntax to embed the documentation rendering of an entire object (method, class, module) inside of an extra file. This is useful when writing non-API based guides that might require listing a few helper methods or classes. The GettingStarted discussed this syntax in more detail (with example usage).

Added improved templates API for custom CSS/JS/menus (0.7.0)

Plugin & template developers can now more easily insert custom stylesheet or JavaScript files in their customized templates, thanks to an abstraction of the template API. This is documented in the docs/Templatesdocs/Templates.md document. In addition to custom CSS/JS, developers can also create custom menu tabs in both the framed and non framed version of the default theme.

Added Ruby markup type (`-m ruby`) (0.7.0)

The Ruby markup type (-m ruby) will now use syntax highlighting for all formatting. This is probably not useful as a global switch, but can be used on individual extra files using the metadata markup specification discussed above.

Added state tracking variables to Parser/Handler architecture (0.7.0)

The parser and handler architecture now contain state variables YARD::Handlers::Base#extra_state and YARD::Handlers::Processor#globals to share data across handlers and the entire processing phase. #extra_state provided a place to store per-file data, while #globals gives the developer access to inter-file state when parsing multiple files at once.

Added before/after callbacks to SourceParser (0.7.0)

The YARD::Parser::SourceParser class can now register callbacks to execute code before and after parsing of file globs, as well as before and after parsing of individual files. This allows plugin developers to perform setup/teardown (and set global state or update the YARD::Registry).

See the documentation for the following methods:

Can now use `--yardopts FILE` to specify a custom yardopts file (0.7.0)

The yardoc command now supports --yardopts FILE to specify custom .yardopts options files. This is useful if you have multiple documentation sets, such as a guide documentation set and an API documentation set.

Added new `-t guide` template for guide based docs (0.7.0)

You can now write guide style documentation using a new 'guide' template that only generates documentation for extra files. You would use it in the form:

yardoc -t guide - README GettingStarted FAQ TroubleShooting LICENSE

This creates the sections for the readme, a getting started, frequently asked questions, trouble shooting and license page.

If you need to refer to class / method documentation, you can embed API documentation using the {render:Object} tag discussed above.

Github Flavoured Markdown now works out-of-box (0.7.4)

Due to the growing popularity of Github-Flavoured-Markdown (GFM), YARD now uses the Redcarpet library as the default Markdown formatting library with GFM fenced code blocks enabled. This means that you can use fenced code blocks inside of Markdown files with redcarpet installed without any extra code. Previously, users who wanted GFM in their Markdown would have to specify -m markdown -M redcarpet, but this is now the default behaviour for YARD.

Note that you can still specify language types in code blocks without GFM in YARD by using the "!!!lang" prefix syntax. For example (plain means no markup):

!!!plain
Some code
block here.

The GFM version would be:

```plain
Some code
block here.
```

Added `-m textile_strict` and `-m pre` markup types (0.7.4)

A new "textile_strict" markup type was added which behaves exactly like "textile" except it enables hard breaks, so newlines behave as line breaks in the HTML (using <br> tags). This option is added for users who want the classic textile behaviour.

Reorganized markup types 'text' and 'none' (0.7.4)

Due to the new pre markup type, the behaviour for text and none were slightly reorganized to be more intuitive. The following behaviours now represent these markup types:

pre: Used to wrap text inside <pre> tags
text: No formatting except for hard breaks (<br>) on newlines
none: No formatting at all.

In all cases, HTML is escaped from input. If you want no HTML escaping, use the html markup type.

Add support for `rb_define_alias` (0.7.4)

CRuby code can now make use of the rb_define_alias function. Documentation for aliases is not supported, however.

What's New in 0.6.x?

Local documentation server for RubyGems or projects (yard server) (0.6.0)
Groups support for method listing (0.6.0)
Single file template (--one-file) support (0.6.0)
yard CLI executable with pluggable commands (0.6.0)
yard diff command to object-diff two versions of a project (0.6.0)
Added --asset option to yardoc (0.6.0)
New template API (0.6.0)
HTML template now adds inline Table of Contents for extra files pages (0.6.0)
Removed --incremental in favour of --use-cache (0.6.0)
Ad-hoc tag registration via yardoc CLI (--tag, etc.) (0.6.0)
Added --transitive-tags to register transitive tags (0.6.0)
yardoc now displays RDoc-like statistics (--no-stats to hide) (0.6.0)
yri now works on constants (0.6.0)
Plugins are no longer auto-loaded (added --plugin switch) (0.6.2)
Added YARD::Config API and ~/.yard/config configuration file (0.6.2)
Added yard config command to view/edit configuration (0.6.2)
Added yard server -t template path switch (0.6.2)
Added YARD::Server.register_static_path for static server assets (0.6.2)
YARD::Registry is now thread local (0.6.5)
Support for ripper gem in Ruby 1.8.7 (0.6.5)

Local documentation server for RubyGems or projects (`yard server`) (0.6.0)

The new yard server command spawns a documentation server that can serve either documentation for a local project or installed RubyGems. The server will host (by default) on http://localhost:8808.

To serve documentation for the active project (in the current directory):

$ yard server

The server can also run in "incremental" mode for local projects. In this situation, any modified sources will immediately be updated at each request, ensuring that the server always serve the code exactly as it is on disk. Documenting your code in this fashion essentially gives you an efficient a live preview without running a separate command everytime you make a change. To serve documentation for the active project in incremental mode:

$ yard server --reload

Note that in incremental mode, objects or method groupings cannot be removed. If you have removed objects or modified groupings, you will need to flush the cache by deleting .yardoc and (optionally) restarting the server.

The documentation server can also serve documentation for all installed gems on your system, similar to gem server, but using YARD's functionality and templates. To serve documentation for installed gems:

$ yard server --gems

Documentation for the gem need not be previously generated at install-time. If documentation for the gem has not been generated, YARD will do this for you on-the-fly. It is therefore possible to speed up your gem installs by using gem install GEMNAME --no-rdoc without repercussion. You can also add this switch to your ~/.gemrc file so that you don't need to re-type it each time. See this link for exact instructions.

Groups support for method listing (0.6.0)

You can now organize methods in a class/module into logical separated groups. These groups apply lexically and are listed in the order they are defined. For instance, to define a group:

# @group Rendering an Object

# Documentation here
def foo; end

# Extra documentation...
def bar; end

# @group Another Group

def aaa; end

Note that these @group and @endgroup declarations are not "tags" and should always be separated with at least 1 line of whitespace from any other documentation or code.

In the above example, "Rendering an Object" will be listed with "foo" and "bar" above "Another Group", even though "aaa" comes before the two other methods, alphabetically. To end a group, use @endgroup. It is not necessary to end a group to start a new one, only if there is an object following the group that should not belong in any group.

# @group Group 1

def foo; end

# @endgroup

# This method should not be listed in any group
def bar; end

Single file template (`--one-file`) support (0.6.0)

yardoc now has the --one-file option to generate a single-file template for small scripts and libraries. In this case, any comments at the top of the script file will be recognized as a README.

`yard` CLI executable with pluggable commands (0.6.0)

The yardoc and yri commands are not deprecated and can continue to be used. They are shortcuts for yard doc and yard ri respectively. However, yard-graph has been removed.

YARD now has a yard executable which combines all pre-existing and new commands into a single pluggable command that is both easier to remember and access. To get a list of commands, type yard --help.

If you are a plugin developer, you can create your own yard command by first subclassing the YARD::CLI::Command class and then registering this class with the YARD::CLI::CommandParser.commands list. For instance:

YARD::CLI::CommandParser.commands[:my_command] = MyCommandClass

The above line will enable the user to execute yard my_command [options].

`yard diff` command to object-diff two versions of a project (0.6.0)

One of the built-in commands that comes with the new yard executable is the ability to do object-oriented diffing across multiple versions of the same project, either by 2 versions of a gem, or 2 working copies. Just like regular diffing tells you which lines have been added/removed in a file, object diffing allows you to see what classes/methods/modules have been added/removed between versions of a codebase.

For an overview of how to use yard diff, see YARD Object Oriented Diffing.

`yard stats` to display statistics and undocumented objects (0.6.0)

YARD now outputs the following statistics when yard stats is run:

Files:         125
Modules:        35 (    4 undocumented)
Classes:       139 (   29 undocumented)
Constants:      53 (   20 undocumented)
Methods:       602 (   70 undocumented)
 85.16% documented

Note that these statistics are based on what you have set to show in your documentation. If you use @private tags and/or do not display private/protected methods in your documentation, these will not show up as undocumented. Therefore this metric is contextual.

You can also specifically list all undocumented objects (and their file locations) with the --list-undoc option.

Added `--asset` option to `yardoc` (0.6.0)

The yardoc command can now take the --asset option to copy over files/directories (recursively) to the output path after generating documentation. The format of the argument is "from:to" where from is the source path and to is the destination. For instance, YARD uses the following syntax in the .yardopts file to copy over image assets from the 'docs/images' directory into the 'images' directory after generating HTML:

--asset docs/images:images

New template API (0.6.0)

The new template API allows for easier insertion of sections within an inherited template. You should no longer need to insert by index, an error-prone process that could break when a template is updated. Instead of:

sections.last.place(:my_section).before(:another_section)

use:

sections.place(:my_section).before_any(:another_section)

You can see more in the Templates document.

HTML template now adds inline Table of Contents for extra files pages (0.6.0)

A table of contents is now generated dynamically using JavaScript for extra file pages (such as README's, or this document). It is generated based off the headers (h1,h2,... tags) used in the document, and can be floated to the right or listed inline on the page.

Ad-hoc tag registration via `yardoc` CLI (`--tag`, etc.) (0.6.0)

Simple meta-data tags can now be added at the command-line and registered to display in templates in a number of pre-defined ways. For instance, to create a freeform text tag, use the following:

--tag my_tag_name:"My Tag Title"

You can also create a "typed" tag (similar to @return), a typed named tag (similar to @param) as well as various combinations. The full list of options are listed in yardoc --help under the "Tag Options" section.

If you wish to create a tag to store data but do not wish to show this data in the templates, use the --hide-tag option to hide it from generated output:

--hide-tag my_tag_name

Added `--transitive-tags` to register transitive tags (0.6.0)

Transitive tags are tags that apply to all descendants of a namespace (class or module) when documented on that namespace. For instance, the @since tag is a transitive tag. Applying @since to a class will automatically apply @since to all methods in the class. Creating a @since tag directly on a method will override the inherited value.

You can specify transitive tags on the command-line by using this option. Note that the tags must already exist (built-in or created with the --tag option) to be specified as transitive. If you wish to do this programmatically, see the YARD::Tags::Library.transitive_tags attribute.

`yardoc` now displays RDoc-like statistics (`--no-stats` to hide) (0.6.0)

As seen in the yard stats feature overview, yardoc displays RDoc-like statistics when it is run. The output is equivalent to typing yard stats. To hide this output when yardoc is run, use --no-stats.

`yri` now works on constants (0.6.0)

Templates have now been added for text view of constants, which displays any documentation and the constant value.

Plugins are no longer auto-loaded (added `--plugin` switch) (0.6.2)

This is a backwards-incompatible change that disables plugins from automatically loading when YARD starts up. From now on, you should manually declare which plugins your project is using by adding --plugin PLUGINNAME to a .yardopts file in the root of your project. You can also re-enable autoloaded plugins by setting load_plugins to true in your configuration file (yard config load_plugins true, see next item). You can also set autoload_plugins to a list of plugins to be automatically loaded on start.

If you are a YARD plugin author, please make sure to inform your users of these changes.

Note that --plugin switches passed on the commandline (not via .yardopts) are parsed before commands are loaded, and therefore can add in new CLI commands.

Added `YARD::Config` API and `~/.yard/config` configuration file (0.6.2)

There is a new global configuration API that can be accessed programmatically and set via the ~/.yard/config file. The file is encoded as a YAML file, and looks like:

:load_plugins: false
:ignored_plugins:
  - my_plugin
  - my_other_plugin
:autoload_plugins:
  - my_autoload_plugin
:safe_mode: false

You can also set configuration options via the command-line (see next item).

Added `yard config` command to view/edit configuration (0.6.2)

A new yard config command was created to view or edit the configuration file via the commandline.

To view the current configuration use yard config --list.
To view a specific item use yard config ITEMNAME
To modify an item value use yard config ITEMNAME VALUE

Added `yard server -t` template path switch (0.6.2)

The yard server command now accepts -t or --template-path to register a new template path for template customization.

Added `YARD::Server.register_static_path` for static server assets (0.6.2)

The server now supports a command to register static asset paths. If you are extending the YARD::Server modules, make sure to register your asset paths through this method.

YARD::Registry is now thread local (0.6.5)

Creating a new thread will now implicitly load a new Registry that can be used to parse and process new code objects independently of the other threads. Note that this means you can no longer use the Registry across threads; you must either access the threadlocal object directly, or synchronize threads to do the processing in the initial registry's thread.

Support for ripper gem in Ruby 1.8.7 (0.6.5)

YARD now supports the Ruby 1.8.7 port of the ripper gem to improve parsing of source, both in terms of performance and functionality. When the ripper gem is available, YARD will use the "new-style" handlers. You can take advantage of this functionality by performing a gem install ripper.

What's New in 0.5.x?

Support for documenting native Ruby C code (0.5.0)
Incremental parsing and output generation with yardoc -c (0.5.0, 0.5.3)
Improved yri support to perform lookups on installed Gems (0.5.0)
Added yardoc --default-return and yardoc --hide-void-return (0.5.0)
Multiple syntax highlighting language support (0.5.0)
New .yardoc format (0.5.0)
Support for yard-doc-* gem packages as hosted .yardoc dbs (0.5.1)
Support for extra search paths in yri (0.5.1)
Generating HTML docs now adds frames view (0.5.3)
Tree view for class list (0.5.3)
Ability to specify markup format of extra files (0.5.3)
Keyboard shortcuts for default HTML template (0.5.4)

Support for documenting native Ruby C code (0.5.0)

It is now possible to document native Ruby extensions with YARD with a new C parser mostly borrowed from RDoc. This enables the ability to document Ruby's core and stdlibs which will be hosted on http://yardoc.org/docs. In addition, the .yardoc dump for the Ruby-core classes will become available as an installable gem for yri support (see #3).

Incremental parsing and output generation with `yardoc -c` (0.5.0, 0.5.3)

Note: in 0.5.3 and above you must use --incremental to incrementally generate HTML, otherwise only parsing will be done incrementally but HTML will be generated with all objects. --incremental implies -c, so no need to specify them both.

YARD now compares file checksums before parsing when using yardoc -c (aka yardoc --use-cache) to do incremental parsing of only the files that have changed. HTML

What's New in 0.8.x?

Directives (new behavioural tag syntax) (0.8.0)

Notable features of directives

Directives do not need to be attached to object docstrings

@!method and @!attribute directives improved

New @!parse directive to parse Ruby code

Backward incompatible changes to @!macro directive

Added --embed-mixin(s) to embed mixins into class docs (0.8.0)

Internationalization (I18n) support for translating docs

New C parser / handlers architecture (0.8.0)

YARD will now warn if @param name not in method params (0.8.0)

Added support for module_function calls in Ruby code (0.8.0)

Greatly improved tag documentation using custom template (0.8.0)

Tags can now contain '.' for namespacing (0.8.0)

Added "frames" links for non-framed pages for better nav (0.8.0)

Added Gemfile support to YARD server for local gem sets (0.8.0)

Server now displays README on index route like static docs (0.8.0)

Added line numbers to yard stats --list-undoc --compact (0.8.0)

Single object db now default (multi-object db unsupported) (0.8.0)

Added --api tag to generate documentation for API sets (0.8.1)

Added --non-transitive-tag to disable transitive tag (0.8.3)

Added -B/--bind to bind to a port in yard server (0.8.4)

Added asciidoc markup type support (0.8.6)

Added yard markups command to list available markup types (0.8.6)

Added yard display command to display formatted objects (0.8.6)

Added --layout to yard display command (0.8.6.1)

What's New in 0.7.x?

Macro support and detection of DSL methods (0.7.0)

Inherited attributes now show in HTML output (0.7.0)

The 'app' directory is now parsed by default (0.7.0)

Added support for metadata (@title, @markup) in extra files/readmes (0.7.0)

Added yard list command (alias for yardoc --list) (0.7.0)

Added Git support in yard diff (0.7.0)

Added {include:file:FILENAME} syntax (0.7.0)

Added {render:OBJECT} syntax to embed object docs in extra files (0.7.0)