# Class: YARD::Tags::Tag

Inherits:
  Object
  - Object
  - YARD::Tags::Tag
  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

- #name ⇒ String?
- #object ⇒ CodeObjects::Base

  The associated object.

- #tag_name ⇒ String

  The name of the tag.

- #text ⇒ String?
- #types ⇒ Array<String>?

## Instance Method Summary collapse

- #explain_types ⇒ String?

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

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

  Creates a new tag object with a tag name and text.

- #type ⇒ String

  Convenience method to access the first type specified.

## 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`, `nil`) —

  the descriptive text for this tag, or nil if none provided

- 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:

- (`CodeObjects::Base`) —

  the associated object

    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:

- #types

    57
    58
    59

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

    def type
      types.first
    end