Class: YARD::Tags::Tag

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

Overview

Represents a metadata tag value (+@tag+). Tags can have any combination of #types, #name and #text, or none of the above.

Examples:

Programmatic tag creation

# The following docstring syntax:
#   @param [String, nil] arg an argument
#
# is equivalent to:
Tag.new(:param, 'an argument', ['String', 'nil'], 'arg')

Direct Known Subclasses

DefaultTag, OptionTag, OverloadTag

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(tag_name, text, types = nil, name = nil) ⇒ Tag

Creates a new tag object with a tag name and text. Optionally, formally declared types and a key name can be specified.

Types are mainly for meta tags that rely on type information, such as param, return, etc.

Key names are for tags that declare meta data for a specific key or name, such as param, raise, etc.

Parameters:

  • tag_name (#to_s) —

    the tag name to create the tag for

  • text (String) —

    the descriptive text for this tag

  • types (Array<String>) (defaults to: nil) —

    optional type list of formally declared types for the tag

  • name (String) (defaults to: nil) —

    optional key name which the tag refers to



44
45
46
47
48
49
 
# File 'lib/yard/tags/tag.rb', line 44

def initialize(tag_name, text, types = nil, name = nil)
  @tag_name = tag_name.to_s
  @text = text
  @name = name
  @types = (types ? [types].flatten.compact : nil)
end

Instance Attribute Details

#name ⇒ String

Returns a name associated with the tag.

Returns:

  • (String) —

    a name associated with the tag



26
27
28
 
# File 'lib/yard/tags/tag.rb', line 26

def name
  @name
end

#object ⇒ CodeObjects::Base

Returns the associated object.

Returns:



29
30
31
 
# File 'lib/yard/tags/tag.rb', line 29

def object
  @object
end

#tag_name ⇒ String

Returns the name of the tag.

Returns:

  • (String) —

    the name of the tag



15
16
17
 
# File 'lib/yard/tags/tag.rb', line 15

def tag_name
  @tag_name
end

#text ⇒ String?

Returns:

  • (String) —

    the tag text associated with the tag

  • (nil) —

    if no tag text is supplied



19
20
21
 
# File 'lib/yard/tags/tag.rb', line 19

def text
  @text
end

#types ⇒ Array<String>?

Returns:

  • (Array<String>) —

    a list of types associated with the tag

  • (nil) —

    if no types are associated with the tag



23
24
25
 
# File 'lib/yard/tags/tag.rb', line 23

def types
  @types
end

Instance Method Details

#explain_types ⇒ String?

Provides a plain English summary of the type specification, or nil if no types are provided or parseable.

Returns:

  • (String) —

    a plain English description of the associated types

  • (nil) —

    if no types are provided or not parseable



65
66
67
68
 
# File 'lib/yard/tags/tag.rb', line 65

def explain_types
  return nil if !types || types.empty?
  TypesExplainer.explain(*types)
end

#type ⇒ String

Convenience method to access the first type specified. This should mainly be used for tags that only specify one type.

Returns:

  • (String) —

    the first of the list of specified types

See Also:



56
57
58
 
# File 'lib/yard/tags/tag.rb', line 56

def type
  types.first
end