Class: YARD::Tags::Library

Relationships & Source Files
Inherits:	Object
Defined in:	lib/yard/tags/library.rb

Overview

Keeps track of all the registered meta-data tags and directives. Also allows for defining of custom tags and customizing the tag parsing syntax.

Defining Custom Meta-Data Tags

To define a custom tag, use .define_tag. You should pass the tag name and the factory method to use when creating the tag. If you do not provide a factory method to use, it will default to DefaultFactory#parse_tag

You can also define tag objects manually by simply implementing a "tagname_tag" method that returns a Tag object, but they will not take advantage of tag factory parsing:

def mytag_tag(text) Tag.new(:mytag, text) end

Defining Custom Directives

Directives can be defined by calling the .define_directive method, taking the directive name, an optional tag factory parser method (to parse the data in the directive into a temporary Tag object) and a Directive subclass that performs the directive processing. For more information on creating a Directive subclass, see the Directive class documentation.

Similar to tags, Directives can also be defined manually, in this case using the method name "mydirective_directive" and returning a new Directive object:

def mydirective_directive(tag, parser) MyDirective.new(tag, parser) end

Namespaced Tags

In YARD 0.8.0+, tags can be namespaced using the '.' character. It is recommended to namespace project specific tags, like @yard.tag_name, so that tags do not collide with other plugins or new built-in tags.

Adding/Changing the Tag Syntax

If you have specialized tag parsing needs you can substitute the #factory object with your own by setting Library.default_factory to a new class with its own parsing methods before running ::YARD. This is useful if you want to change the syntax of existing tags (@see, @since, etc.)

Examples:

Defining a custom tag

define_tag "Parameter", :param, :with_types_and_name
define_tag "Author", :author

Defining a custom directive

define_directive :method, :with_title_and_text, MethodDirective

See Also:

Class Attribute Summary

.default_factory rw

Replace the factory object responsible for parsing tags by setting this to an object (or class) that responds to parse_TAGNAME methods where TAGNAME is the name of the tag.
.default_factory=(factory) rw

Replace the factory object responsible for parsing tags by setting this to an object (or class) that responds to parse_TAGNAME methods where TAGNAME is the name of the tag.
.instance ⇒ Library rw
.instance=(value) ⇒ Library rw
.labels ⇒ SymbolHash{Symbol=>String} readonly
.transitive_tags ⇒ Array<Symbol> rw

Sets the list of tags that should apply to any children inside the namespace they are defined in.
.visible_tags ⇒ Array<Symbol> rw

Sets the list of tags to display when rendering templates.

Class Method Summary

.define_directive(tag, tag_meth = nil, directive_class)
.define_tag(label, tag, meth = nil)

Convenience method to define a new tag using one of Tag's factory methods, or the regular DefaultFactory#parse_tag factory method if none is supplied.
.directive_method_name(tag_name)
.factory_method_for(tag) ⇒ Symbol, ...

Returns the factory method used to parse the tag text for a specific tag.
.factory_method_for_directive(directive) ⇒ Symbol, ...

Returns the factory method used to parse the tag text for a specific directive.
.new(factory = Library.default_factory) ⇒ Library constructor
.sorted_labels ⇒ Array<Symbol>, String

Sorts the labels lexically by their label name, often used when displaying the tags.
.tag_method_name(tag_name)
.tag_or_directive_method_name(tag_name, type = 'tag') private

Instance Attribute Summary

#factory rw

A factory class to handle parsing of tags, defaults to .default_factory

Instance Method Summary

#directive_create(tag_name, tag_buf, parser) ⇒ Directive

Creates a new directive with tag information and a docstring parser object.
#has_directive?(tag_name) ⇒ Boolean
#has_tag?(tag_name) ⇒ Boolean
#tag_create(tag_name, tag_buf) ⇒ Tag

Creates a new Tag object with a given tag name and data.
#abstract_tag private

Marks a class/module/method as abstract with optional implementor information.
#api_tag private

Declares the API that the object belongs to.
#attr_reader_tag private deprecated Deprecated.
Use the more powerful @!attribute directive instead.
#attr_tag private deprecated Deprecated.
Use the more powerful @!attribute directive instead.
#attr_writer_tag private deprecated Deprecated.
Use the more powerful @!attribute directive instead.
#attribute_directive private
#author_tag private

List the author or authors of a class, module, or method.
#deprecated_tag private

Marks a method/class as deprecated with an optional description.
#directive_call(tag, parser) ⇒ Directive private
#endgroup_directive private
#example_tag private

Show an example snippet of code for an object.
#group_directive private
#macro_directive private
#method_directive private
#note_tag private

Adds an emphasized note at the top of the docstring for the object.
#option_tag private

Describe an options hash in a method.
#overload_tag private

Describe that your method can be used in various contexts with various parameters or return types.
#param_tag private

Documents a single method parameter (either regular or keyword) with a given name, type and optional description.
#parse_directive private
#private_tag private

Declares that the logical visibility of an object is private.
#raise_tag private

Describes that a method may raise a given exception, with an optional description of what it may mean.
#return_tag private

Describes the return value (and type or types) of a method.
#scope_directive private

Sets the scope of a DSL method.
#see_tag private

"See Also" references for an object.
#send_to_factory(tag_name, meth, text) private
#since_tag private

Lists the version that the object was first added.
#todo_tag private

Marks a TODO note in the object being documented.
#version_tag private

Lists the version of a class, module or method.
#visibility_directive private

Sets the visibility of a DSL method.
#yield_tag private

Describes what a method might yield to a given block.
#yieldparam_tag private

Defines a parameter yielded by a block.
#yieldreturn_tag private

Documents the value and type that the block is expected to return to the method.

Constructor Details

.new(factory = Library.default_factory) ⇒ `Library`

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 260


def initialize(factory = Library.default_factory)
  self.factory = factory
end

Class Attribute Details

.default_factory (rw)

Replace the factory object responsible for parsing tags by setting this to an object (or class) that responds to parse_TAGNAME methods where TAGNAME is the name of the tag.

You should set this value before performing any source parsing with ::YARD, otherwise your factory class will not be used.

Examples:

YARD::Tags::Library.default_factory = MyFactory

See Also:

DefaultFactory

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 83


def default_factory
  @default_factory ||= DefaultFactory.new
end

.default_factory=(factory) (rw)

Replace the factory object responsible for parsing tags by setting this to an object (or class) that responds to parse_TAGNAME methods where TAGNAME is the name of the tag.

You should set this value before performing any source parsing with ::YARD, otherwise your factory class will not be used.

See additional method definition at line 83.

Examples:

YARD::Tags::Library.default_factory = MyFactory

See Also:

DefaultFactory

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 87


def default_factory
  @default_factory ||= DefaultFactory.new
end

.instance ⇒ `Library` (rw)

Returns:

(Library) —
the main Library instance object.

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 67


def instance
  @instance ||= new
end

.instance=(value) ⇒ `Library` (rw)

Returns:

(Library) —
the main Library instance object.

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 67


def instance
  @instance ||= new
end

.labels ⇒ SymbolHash{`Symbol`=>String} (readonly)

Returns:

(SymbolHash{Symbol=>String}) —
the map of tag names and their respective display labels.

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 63


attr_reader :labels

.transitive_tags ⇒ Array<`Symbol`> (rw)

Sets the list of tags that should apply to any children inside the namespace they are defined in. For instance, a "@since" tag should apply to all methods inside a module it is defined in. Transitive tags can be overridden by directly defining a tag on the child object.

Returns:

(Array<Symbol>) —
a list of transitive tags

Since:

0.6.0

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 136


attr_accessor :transitive_tags

.visible_tags ⇒ Array<`Symbol`> (rw)

Sets the list of tags to display when rendering templates. The order of tags in the list is also significant, as it represents the order that tags are displayed in templates.

You can use the Array#place to insert new tags to be displayed in the templates at specific positions:

Library.visible_tags.place(:mytag).before(:return)

Returns:

(Array<Symbol>) —
a list of ordered tags

Since:

0.6.0

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 127


attr_accessor :visible_tags

Class Method Details

.define_directive(tag, tag_meth = nil, directive_class)

Convenience method to define a new directive using a Tag factory method and Directive subclass that implements the directive callbacks.

Parameters:

tag (#to_s) —
the tag name of the directive
tag_meth (#to_s) (defaults to: nil) —
the tag factory method to use when parsing tag information
the (Class<Directive>) —
directive class that implements the directive behaviour

See Also:

.define_tag

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 196


def define_directive(tag, tag_meth = nil, directive_class = nil)
  directive_meth = directive_method_name(tag)
  if directive_class.nil?
    directive_class = tag_meth
    tag_meth = nil
  end
  class_eval <<-eof, __FILE__, __LINE__
    def #{directive_meth}(tag, parser)
      directive_call(tag, parser)
    end
  eof

  @factory_methods ||= SymbolHash.new(false)
  @factory_methods.update(tag => tag_meth)
  @directive_factory_classes ||= SymbolHash.new(false)
  @directive_factory_classes.update(tag => directive_class)

  tag
end

.define_tag(label, tag, meth = nil)

Convenience method to define a new tag using one of Tag's factory methods, or the regular DefaultFactory#parse_tag factory method if none is supplied.

Parameters:

label (#to_s) —
the label used when displaying the tag in templates
tag (#to_s) —
the tag name to create
meth (#to_s, Class<Tag>) (defaults to: nil) —
the Tag factory method to call when creating the tag or the name of the class to directly create a tag for

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 157


def define_tag(label, tag, meth = nil)
  tag_meth = tag_method_name(tag)
  if meth.is_a?(Class) && Tag > meth
    class_eval(<<-eof, __FILE__, __LINE__ + 1)
      def #{tag_meth}(text)
        #{meth}.new(#{tag.inspect}, text)
      end
    eof
  else
    class_eval(<<-eof, __FILE__, __LINE__ + 1)
      begin; undef #{tag_meth}; rescue NameError; end
      def #{tag_meth}(text)
        send_to_factory(#{tag.inspect}, #{meth.inspect}, text)
      end
    eof
  end

  @labels ||= SymbolHash.new(false)
  @labels.update(tag => label)
  @factory_methods ||= SymbolHash.new(false)
  @factory_methods.update(tag => meth)
  tag
end

.directive_method_name(tag_name)

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 220


def directive_method_name(tag_name)
  tag_or_directive_method_name(tag_name, 'directive')
end

.factory_method_for(tag) ⇒ `Symbol`, ...

Returns the factory method used to parse the tag text for a specific tag

Parameters:

tag (Symbol) —
the tag name

Returns:

(Symbol) —
the factory method name for the tag
(Class<Tag>, Symbol) —
the Tag class to use to parse the tag or the method to call on the factory class
(nil) —
if the tag is freeform text

Since:

0.6.0

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 99


def factory_method_for(tag)
  @factory_methods[tag]
end

.factory_method_for_directive(directive) ⇒ `Symbol`, ...

Returns the factory method used to parse the tag text for a specific directive

Parameters:

directive (Symbol) —
the directive name

Returns:

(Symbol) —
the factory method name for the tag
(Class<Tag>, Symbol) —
the Tag class to use to parse the tag or the methods to call on the factory class
(nil) —
if the tag is freeform text

Since:

0.8.0

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 112


def factory_method_for_directive(directive)
  @directive_factory_classes[directive]
end

.sorted_labels ⇒ Array<`Symbol`>, String

Sorts the labels lexically by their label name, often used when displaying the tags.

Returns:

(Array<Symbol>, String) —
the sorted labels as an array of the tag name and label

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 142


def sorted_labels
  labels.sort_by {|a| a.last.downcase }
end

.tag_method_name(tag_name)

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 216


def tag_method_name(tag_name)
  tag_or_directive_method_name(tag_name)
end

.tag_or_directive_method_name(tag_name, type = 'tag') (private)

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 226


def tag_or_directive_method_name(tag_name, type = 'tag')
  "#{tag_name.to_s.tr('.', '_')}_#{type}"
end

Instance Attribute Details

#factory (rw)

A factory class to handle parsing of tags, defaults to .default_factory

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 258


attr_accessor :factory

Instance Method Details

#abstract_tag (private)

Marks a class/module/method as abstract with optional implementor information.

Examples:

# @abstract Subclass and override {#run} to implement
#   a custom Threadable class.
class Runnable
  def run; raise NotImplementedError end
end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 312


define_tag "Abstract",           :abstract

#api_tag (private)

Note:

This tag is transitive. If it is applied on a namespace (module or class), it will immediately be applied to all children objects of that namespace unless it is redefined on the child object.

Note:

The special name +@api private+ does display a notice in documentation if it is listed, letting users know that the method is not to be used by external components.

Declares the API that the object belongs to. Does not display in output, but useful for performing queries (+yardoc --query+). Any text is allowable in this tag, and there are no predefined values.

Examples:

class Post
  # @api private
  def reset_table!; table.flush end
end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 327


define_tag "API Visibility",     :api

#attr_reader_tag (private)

Deprecated.

Use the more powerful @!attribute directive instead.

Note:

This attribute is only applicable on class docstrings

Declares a readonly attribute on a Struct or class.

Examples:

# @attr_reader [String] name the name of the structure
# @attr_reader [Fixnum] size the size of the structure
class MyStruct < Struct; end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 347


define_tag "Attribute Getter",   :attr_reader, :with_types_and_name

#attr_tag (private)

Deprecated.

Use the more powerful @!attribute directive instead.

Note:

This attribute is only applicable on class docstrings

Declares a readwrite attribute on a Struct or class.

Examples:

# @attr [String] name the name of the structure
# @attr [Fixnum] size the size of the structure
class MyStruct < Struct; end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 337


define_tag "Attribute",          :attr,        :with_types_and_name

#attr_writer_tag (private)

Deprecated.

Use the more powerful @!attribute directive instead.

Note:

This attribute is only applicable on class docstrings

Declares a writeonly attribute on a Struct or class.

Examples:

# @attr_reader [String] name the name of the structure
# @attr_reader [Fixnum] size the size of the structure
class MyStruct < Struct; end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 357


define_tag "Attribute Setter",   :attr_writer, :with_types_and_name

#attribute_directive (private)

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 598


define_directive :attribute, :with_types_and_title, AttributeDirective

#author_tag (private)

List the author or authors of a class, module, or method.

Examples:

# @author Foo Bar <foo@bar.com>
class MyClass; end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 364


define_tag "Author",             :author

#deprecated_tag (private)

Marks a method/class as deprecated with an optional description. The description should be used to inform users of the recommended migration path, and/or any useful information about why the object was marked as deprecated.

Examples:

Deprecate a method with a replacement API

# @deprecated Use {#bar} instead.
def foo; end

Deprecate a method with no replacement

class Thread
  # @deprecated Exiting a thread in this way is not reliable and
  #   can cause a program crash.
  def kill; end
end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 380


define_tag "Deprecated",         :deprecated

#directive_call(tag, parser) ⇒ Directive (private)

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 244


def directive_call(tag, parser)
  meth = self.class.factory_method_for_directive(tag.tag_name)
  if meth <= Directive
    meth = meth.new(tag, parser)
    meth.call
    meth
  else
    meth.call(tag, parser)
  end
end

#directive_create(tag_name, tag_buf, parser) ⇒ Directive

Creates a new directive with tag information and a docstring parser object.

Parameters:

tag_name (String) —
the name of the tag
tag_buf (String) —
the tag data
parser (DocstringParser) —
the parser object parsing the docstring

Returns:

(Directive) —
the newly created directive

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 290


def directive_create(tag_name, tag_buf, parser)
  meth = self.class.factory_method_for(tag_name)
  tag = send_to_factory(tag_name, meth, tag_buf)
  meth = self.class.directive_method_name(tag_name)
  send(meth, tag, parser)
end

#endgroup_directive (private)

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 601


define_directive :endgroup,                         EndGroupDirective

#example_tag (private)

Show an example snippet of code for an object. The first line is an optional title.

Examples:

# @example Reverse a String
#   "mystring".reverse #=> "gnirtsym"
def reverse; end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 391


define_tag "Example",            :example, :with_title_and_text

#group_directive (private)

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 603


define_directive :group,                            GroupDirective

#has_directive?(tag_name) ⇒ `Boolean`

Parameters:

tag_name (#to_s) —
the name of the tag to look for

Returns:

(Boolean) —
whether a directive by the given name is registered in the library.

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 280


def has_directive?(tag_name)
  tag_name && respond_to?(self.class.directive_method_name(tag_name))
end

#has_tag?(tag_name) ⇒ `Boolean`

Parameters:

tag_name (#to_s) —
the name of the tag to look for

Returns:

(Boolean) —
whether a tag by the given name is registered in the library.

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 267


def has_tag?(tag_name)
  tag_name && respond_to?(self.class.tag_method_name(tag_name))
end

#macro_directive (private)

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 607


define_directive :macro, :with_types_and_title,     MacroDirective

#method_directive (private)

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 611


define_directive :method, :with_title_and_text,     MethodDirective

#note_tag (private)

Adds an emphasized note at the top of the docstring for the object

Examples:

# @note This method should only be used in outer space.
def eject; end

See Also:

@todo

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 399


define_tag "Note",               :note

#option_tag (private)

Note:

For keyword parameters, use @param, not @option.

Describe an options hash in a method. The tag takes the name of the options parameter first, followed by optional types, the option key name, a default value for the key and a description of the option. The default value should be placed within parentheses and is optional (can be omitted).

Note that a @param tag need not be defined for the options hash itself, though it is useful to do so for completeness.

Examples:

# @param [Hash] opts the options to create a message with.
# @option opts [String] :subject The subject
# @option opts [String] :from ('nobody') From address
# @option opts [String] :to Recipient email
# @option opts [String] :body ('') The email's body
def send_email(opts = {}) end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 420


define_tag "Options Hash",       :option,      :with_options

#overload_tag (private)

Describe that your method can be used in various contexts with various parameters or return types. The first line should declare the new method signature, and the following indented tag data will be a new documentation string with its own tags adding metadata for such an overload.

Examples:

# @overload set(key, value)
#   Sets a value on key
#   @param key [Symbol] describe key param
#   @param value [Object] describe value param
# @overload set(value)
#   Sets a value on the default key {:foo}
#   @param value [Object] describe value param
def set(*args) end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 439


define_tag "Overloads",          :overload,    OverloadTag

#param_tag (private)

Documents a single method parameter (either regular or keyword) with a given name, type and optional description.

Examples:

# @param url [String] the URL of the page to download
# @param directory [String] the name of the directory to save to
def load_page(url, directory: 'pages') end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 448


define_tag "Parameters",         :param,       :with_types_and_name

#parse_directive (private)

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 614


define_directive :parse, :with_types,               ParseDirective

#private_tag (private)

Note:

This method is not recommended for hiding undocumented or "unimportant" methods. This tag should only be used to mark objects private when Ruby visibility rules cannot do so. In Ruby 1.9.3, you can use private_constant to declare constants (like classes or modules) as private, and should be used instead of @private.

Note:

This tag is transitive. If it is applied on a namespace (module or class), it will immediately be applied to all children objects of that namespace unless it is redefined on the child object.

Declares that the logical visibility of an object is private. In other words, it specifies that this method should be marked private but cannot due to Ruby's visibility restrictions. This exists for classes, modules and constants that do not obey Ruby's visibility rules. For instance, an inner class might be considered "private", though Ruby would make no such distinction.

This tag is meant to be used in conjunction with the --no-private command-line option, and is required to actually remove these objects from documentation output. See README for more information on switches.

If you simply want to set the API visibility of a method, you should look at the @api tag instead.

Examples:

# @private
class InteralImplementation; end

See Also:

@api

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 476


define_tag "Private",            :private

#raise_tag (private)

Describes that a method may raise a given exception, with an optional description of what it may mean.

Examples:

# @raise [AccountBalanceError] if the account does not have
#   sufficient funds to perform the transaction
def withdraw(amount) end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 485


define_tag "Raises",             :raise,       :with_types

#return_tag (private)

Describes the return value (and type or types) of a method. You can list multiple return tags for a method in the case where a method has distinct return cases. In this case, each case should begin with "if ...".

Examples:

A regular return value

# @return [Fixnum] the size of the file
def size; @file.size end

A method returns an ::Array or a single object

# @return [String] if a single object was returned
#   from the database.
# @return [Array<String>] if multiple objects were
#   returned.
def find(query) end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 501


define_tag "Returns",            :return,      :with_types

#scope_directive (private)

Sets the scope of a DSL method. Only applicable to DSL method calls. Acceptable values are 'class' or 'instance'

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 619


define_directive :scope,                            ScopeDirective

#see_tag (private)

"See Also" references for an object. Accepts URLs or other code objects with an optional description at the end. Note that the URL or object will be automatically linked by ::YARD and does not need to be formatted with markup.

Examples:

# Synchronizes system time using NTP.
# @see http://ntp.org/documentation.html NTP Documentation
# @see NTPHelperMethods
class NTPUpdater; end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 513


define_tag "See Also",           :see,         :with_name

#send_to_factory(tag_name, meth, text) (private)

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 233


def send_to_factory(tag_name, meth, text)
  meth = meth.to_s
  send_name = "parse_tag" + (meth.empty? ? "" : "_" + meth)
  if @factory.respond_to?(send_name)
    @factory.send(send_name, tag_name, text)
  else
    raise NoMethodError, "Factory #{@factory.class_name} does not implement factory method :#{meth}."
  end
end

#since_tag (private)

Note:

This tag is transitive. If it is applied on a namespace (module or class), it will immediately be applied to all children objects of that namespace unless it is redefined on the child object.

Lists the version that the object was first added.

Examples:

# @since 1.2.4
def clear_routes; end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 521


define_tag "Since",              :since

#tag_create(tag_name, tag_buf) ⇒ Tag

Creates a new Tag object with a given tag name and data

Returns:

(Tag) —
the newly created tag object

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 273


def tag_create(tag_name, tag_buf)
  send(self.class.tag_method_name(tag_name), tag_buf)
end

#todo_tag (private)

Marks a TODO note in the object being documented. For reference, objects with TODO items can be enumerated from the command line with a simple command:

!!!sh mocker$ yard list --query '@todo' lib/mocker/mocker.rb:15: Mocker lib/mocker/report/html.rb:5: Mocker::Report::Html

::YARD can also be used to enumerate the TODO items from a short script:

!!!ruby require 'yard' YARD::Registry.load!.all.each do |o| puts o.tag(:todo).text if o.tag(:todo) end

Examples:

# @todo Add support for Jabberwocky service.
#   There is an open source Jabberwocky library available
#   at http://jbrwcky.org that can be easily integrated.
class Wonderlander; end

See Also:

@note

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 547


define_tag "Todo Item",          :todo

#version_tag (private)

Lists the version of a class, module or method. This is similar to a library version, but at finer granularity. In some cases, version of specific modules, classes, methods or generalized components might change independently between releases. A version tag is used to infer the API compatibility of a specific object.

Examples:

# The public REST API for http://jbrwcky.org
# @version 2.0
class JabberwockyAPI; end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 560


define_tag "Version",            :version

#visibility_directive (private)

Sets the visibility of a DSL method. Only applicable to DSL method calls. Acceptable values are public, protected, or private.

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 624


define_directive :visibility,                       VisibilityDirective

#yield_tag (private)

Describes what a method might yield to a given block. The types specifier list should not list types, but names of the parameters yielded to the block. If you define parameters with @yieldparam, you do not need to define the parameters in the type specification of @yield as well.

Examples:

# For a block {|a,b,c| ... }
# @yield [a, b, c] Gives 3 random numbers to the block
def provide3values(&block) yield(42, 42, 42) end

See Also:

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 576


define_tag "Yields",             :yield,       :with_types

#yieldparam_tag (private)

Defines a parameter yielded by a block. If you define the parameters with @yieldparam, you do not need to define them via @yield as well.

Examples:

# @yieldparam [String] name the name that is yielded
def with_name(name) yield(name) end

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 585


define_tag "Yield Parameters",   :yieldparam,  :with_types_and_name

#yieldreturn_tag (private)

Documents the value and type that the block is expected to return to the method.

Examples:

# @yieldreturn [Fixnum] the number to add 5 to.
def add5_block(&block) 5 + yield end

See Also:

@return

[ GitHub ]

# File 'lib/yard/tags/library.rb', line 594


define_tag "Yield Returns",      :yieldreturn, :with_types

Class: YARD::Tags::Library

Overview

Defining Custom Meta-Data Tags

Defining Custom Directives

Namespaced Tags

Adding/Changing the Tag Syntax

Class Attribute Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(factory = Library.default_factory) ⇒ Library

Class Attribute Details

.default_factory (rw)

.default_factory=(factory) (rw)

.instance ⇒ Library (rw)

.instance=(value) ⇒ Library (rw)

.labels ⇒ SymbolHash{Symbol=>String} (readonly)

.transitive_tags ⇒ Array<Symbol> (rw)

.visible_tags ⇒ Array<Symbol> (rw)

Class Method Details

.define_directive(tag, tag_meth = nil, directive_class)

.define_tag(label, tag, meth = nil)

.directive_method_name(tag_name)

.factory_method_for(tag) ⇒ Symbol, ...

.factory_method_for_directive(directive) ⇒ Symbol, ...

.sorted_labels ⇒ Array<Symbol>, String

.tag_method_name(tag_name)

.tag_or_directive_method_name(tag_name, type = 'tag') (private)

Instance Attribute Details

#factory (rw)

Instance Method Details

#abstract_tag (private)

#api_tag (private)

#attr_reader_tag (private)

#attr_tag (private)

#attr_writer_tag (private)

#attribute_directive (private)

#author_tag (private)

#deprecated_tag (private)

#directive_call(tag, parser) ⇒ Directive (private)

#directive_create(tag_name, tag_buf, parser) ⇒ Directive

#endgroup_directive (private)

#example_tag (private)

#group_directive (private)

#has_directive?(tag_name) ⇒ Boolean

#has_tag?(tag_name) ⇒ Boolean

#macro_directive (private)

#method_directive (private)

#note_tag (private)

#option_tag (private)

#overload_tag (private)

#param_tag (private)

#parse_directive (private)

#private_tag (private)

#raise_tag (private)

#return_tag (private)

#scope_directive (private)

#see_tag (private)

#send_to_factory(tag_name, meth, text) (private)

#since_tag (private)

#tag_create(tag_name, tag_buf) ⇒ Tag

#todo_tag (private)

#version_tag (private)

#visibility_directive (private)

#yield_tag (private)

#yieldparam_tag (private)

#yieldreturn_tag (private)

.new(factory = Library.default_factory) ⇒ `Library`

.instance ⇒ `Library` (rw)

.instance=(value) ⇒ `Library` (rw)

.labels ⇒ SymbolHash{`Symbol`=>String} (readonly)

.transitive_tags ⇒ Array<`Symbol`> (rw)

.visible_tags ⇒ Array<`Symbol`> (rw)

.factory_method_for(tag) ⇒ `Symbol`, ...

.factory_method_for_directive(directive) ⇒ `Symbol`, ...

.sorted_labels ⇒ Array<`Symbol`>, String

#has_directive?(tag_name) ⇒ `Boolean`

#has_tag?(tag_name) ⇒ `Boolean`