Class: YARD::Tags::Library

Inherits:
Object
  • Object
show all
Defined in:
lib/yard/tags/library.rb

Overview

Holds all the registered meta tags. If you want to extend YARD and add a new meta tag, you can do it in one of two ways.

Method #1

Use Library.define_tag to define a new tag by passing the tag name and the factory method to use when creating the tag. These definitions will be auto expanded into ruby code similar to what is shown in method #2. If you do not provide a factory method to use, it will default to DefaultFactory#parse_tag Example:

define_tag :param, :with_types_and_name
define_tag :author

The first line will expand to the code:

def param_tag(text) tag_factory.parse_tag_with_types_and_name(text) end

The second line will expand to:

def author_tag(text) tag_factory.parse_tag(text) end

Note that tag_factory is the factory object used to parse tags. This value defaults to the DefaultFactory class and can be set by changing Library.default_factory.

Method #2

Write your own tagname_tag method that takes the raw text as a parameter. Example:

def mytag_tag(text)
  # parse your tag contents here
end

This will allow you to use @mytag TEXT to add meta data to classes through the docstring. You can use the #factory object to help parse standard tag syntax.

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.)

See Also:

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(factory = Library.default_factory) ⇒ Library

Returns a new instance of Library.



160
161
162
 
# File 'lib/yard/tags/library.rb', line 160

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

Class Attribute Details

.labels ⇒ Object (readonly)

Returns the value of attribute labels.



45
46
47
 
# File 'lib/yard/tags/library.rb', line 45

def labels
  @labels
end

.transitive_tags ⇒ Array<Symbol>

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 is it 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



103
104
105
 
# File 'lib/yard/tags/library.rb', line 103

def transitive_tags
  @transitive_tags
end

.visible_tags ⇒ Array<Symbol>

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



94
95
96
 
# File 'lib/yard/tags/library.rb', line 94

def visible_tags
  @visible_tags
end

Instance Attribute Details

#factory ⇒ Object

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



158
159
160
 
# File 'lib/yard/tags/library.rb', line 158

def factory
  @factory
end

Class Method Details

.default_factory ⇒ Object 



51
52
53
 
# File 'lib/yard/tags/library.rb', line 51

def default_factory
  @default_factory ||= DefaultFactory.new
end

.default_factory=(factory) ⇒ Object

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

Parameters:

  • factory (Class, Object) —

    the factory that parses all tags

See Also:



68
69
70
 
# File 'lib/yard/tags/library.rb', line 68

def default_factory=(factory)
  @default_factory = factory.is_a?(Class) ? factory.new : factory
end

.define_tag(label, tag, meth = nil) ⇒ Object

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:

  • 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



119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/yard/tags/library.rb', line 119

def define_tag(label, tag, meth = nil)
  if meth.is_a?(Class) && Tag > meth
    class_eval <<-eof, __FILE__, __LINE__
      def #{tag}_tag(text) 
        #{meth}.new(#{tag.inspect}, text) 
      end
    eof
  else
    class_eval <<-eof, __FILE__, __LINE__
      def #{tag}_tag(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

.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>) —

    the Tag class to use to parse the tag

  • (nil) —

    if the tag is freeform text

Since:

  • 0.6.0



79
80
81
 
# File 'lib/yard/tags/library.rb', line 79

def factory_method_for(tag)
  @factory_methods[tag]
end

.instance ⇒ Object 



47
48
49
 
# File 'lib/yard/tags/library.rb', line 47

def instance
  @instance ||= new
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



109
110
111
 
# File 'lib/yard/tags/library.rb', line 109

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