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 Library#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

Instance Attribute Summary

Class Method Summary

Instance Method Summary

Constructor Details

- (Library) initialize(factory = Library.default_factory)

A new instance of Library 



129
130
131
 
# File 'lib/yard/tags/library.rb', line 129

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

Class Attribute Details

+ (Object) default_factory

Returns the value of attribute default_factory 



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

def default_factory
  @default_factory ||= DefaultFactory.new
end

+ (Object) labels (readonly)

Returns the value of attribute labels 



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

def labels
  @labels
end

Instance Attribute Details

- (Object) factory

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



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

def factory
  @factory
end

Class Method Details

+ (Object) define_tag(label, tag, meth = "")

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:

  • (#to_s) tag — the tag name to create
  • (#to_s, Class<Tag>) meth (defaults to: "") — the Tag factory method to call when creating the tag or the name of the class to directly create a tag for 


90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/yard/tags/library.rb', line 90

def define_tag(label, tag, meth = "")
  if meth.is_a?(Class) && Tag > meth
    class_eval <<-eof      def #{tag}_tag(text, raw_text) 
        #{meth}.new(#{tag.inspect}, text, raw_text) 
      end
    eof
, __FILE__, __LINE__
  else
    class_eval <<-eof      def #{tag}_tag(text, raw_text)
        send_to_factory(#{tag.inspect}, #{meth.inspect}, text, raw_text)
      end
    eof
, __FILE__, __LINE__
  end

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

+ (Object) instance 



49
50
51
 
# File 'lib/yard/tags/library.rb', line 49

def instance
  @instance ||= new
end

+ (Array<Symbol>, String) sorted_labels

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 


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

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