Class | YARD::Docstring
In: | lib/yard/docstring.rb
Parent: | String

A documentation string, or "docstring" for short, encapsulates the comments and metadata, or "tags", of an object. Meta-data is expressed in the form +@tag VALUE+, where VALUE can span over multiple lines as long as they are indented. The following +@example+ tag shows how tags can be indented:

      # @example My example
      #   a = "hello world"
      #   a.reverse
      # @version 1.0

Tags can be nested in a documentation string, though the {Tags::Tag} itself is responsible for parsing the inner tags.

### Methods

+ add_tag all= blank? create_tag delete_tag_if delete_tags dup has_tag? hash_flag= line new replace summary tag tags to_raw

### Constants

META_MATCH | = | /^@([a-z_0-9]+)(?:\s+(.*))?$/i |  | Matches a tag at the start of a comment line

### Attributes

all | [R] | @return [String] the raw documentation (including raw tag text)
hash_flag | [R] | @return [Boolean] whether the docstring was started with "##"
line_range | [RW] | @return [Range] line range in the {object}’s file where the docstring was parsed from
object | [RW] | @return [CodeObjects::Base] the object that owns the docstring.
ref_tags | [R] | @return [Array<Tags::RefTag>] the list of reference tags

### Public Class methods

new(content = '', object = nil)

Creates a new docstring with the raw contents attached to an optional object.

@example

      Docstring.new("hello world\n@return Object return", someobj)

@param [String] content the raw comments to be parsed into a docstring

      and associated meta-data.

@param [CodeObjects::Base] object an object to associate the docstring

      with.

### Public Instance methods

+(other)

Adds another {Docstring}, copying over tags.

@param [Docstring, String] other the other docstring (or string) to

      add.

@return [Docstring] a new docstring with both docstrings combines

add_tag(*tags)

Adds a tag or reftag object to the tag list. If you want to parse tag data based on the {Tags::DefaultFactory} tag factory, use {create_tag} instead.

@param [Tags::Tag, Tags::RefTag] tags list of tag objects to add @return [void]

all=(content)

Alias for replace

blank?(only_visible_tags = true)

Returns true if the docstring has no content that is visible to a template.

@param [Boolean] only_visible_tags whether only {Tags::Library.visible_tags}

      should be checked, or if all tags should be considered.

@return [Boolean] whether or not the docstring has content

create_tag(tag_name, tag_buf)

Creates a tag from the {Tags::DefaultFactory tag factory}.

To add an already created tag object, use {add_tag}

@param [String] tag_name the tag name @param [String] tag_buf the text attached to the tag with newlines removed. @return [Tags::Tag, Tags::RefTag] a tag

delete_tag_if(&block)

Deletes all tags where the block returns true @yieldparam [Tags::Tag] tag the tag that is being tested @yieldreturn [Boolean] true if the tag should be deleted @return [void] @since 0.7.0

delete_tags(name)

Delete all tags with `name` @param [String] name the tag name @return [void] @since 0.7.0

dup()

Deep-copies a docstring

@note This method creates a new docstring with new tag lists, but does

      not create new individual tags. Modifying the tag objects will still
      affect the original tags.

@return [Docstring] a new copied docstring @since 0.7.0

has_tag?(name)

Returns true if at least one tag by the name `name` was declared

@param [String] name the tag name to search for @return [Boolean] whether or not the tag `name` was declared

hash_flag=(v)
line()

@return [Fixnum] the first line of the {line_range} @return [nil] if there is no associated {line_range}

replace(content)

Replaces the docstring with new raw content. Called by {all=}. @param [String] content the raw comments to be parsed

summary()

Gets the first line of a docstring to the period or the first paragraph. @return [String] The first line or paragraph of the docstring; always ends with a period.

tag(name)

Convenience method to return the first tag object in the list of tag objects of that name

@example

      doc = Docstring.new("@return zero when nil")
      doc.tag(:return).text  # => "zero when nil"

@param [to_s] name the tag name to return data for @return [Tags::Tag] the first tag in the list of {tags}

tags(name = nil)

Returns a list of tags specified by `name` or all tags if `name` is not specified.

@param [to_s] name the tag name to return data for, or nil for all tags @return [Array<Tags::Tag>] the list of tags by the specified tag name

to_raw()

Reformats and returns a raw representation of the tag data using the current tag and docstring data, not the original text.

@return [String] the updated raw formatted docstring data @since 0.7.0 @todo Add Tags::Tag#to_raw and refactor

[Validate]