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



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

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:

  • (String) —

    a name associated with the tag

  • (nil) —

    if no tag name is supplied



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

def name
  @name
end

#object ⇒ CodeObjects::Base

Returns the associated object.

Returns:



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

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

Returns:

  • (String) —

    a plain English description of the associated types

  • (nil) —

    if no types are provided or not parsable



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

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:



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

def type
  types.first
end