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? delete_tag_if delete_tags dup has_tag? hash_flag= line new new! parser replace summary tag tags to_raw

### Constants

META_MATCH | = | DocstringParser::META_MATCH |  | Matches a tag at the start of a comment line @deprecated Use {DocstringParser::META_MATCH}

### Attributes

all | [R] | @return [String] the raw documentation (including raw tag text)

default_parser

[RW]

@note Plugin developers should make sure to reset this value

      after parsing finishes. This can be done via the
      {Parser::SourceParser.after_parse_list} callback. This will
      ensure that YARD can properly parse multiple projects in
      the same process.

@return [Class<DocstringParser>] the parser class used to parse

      text and optional meta-data from docstrings. Defaults to
      {DocstringParser}.

@see DocstringParser @see Parser::SourceParser.after_parse_list

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. Parsing will be done by the {DocstringParser} class.

@note To properly parse directives with proper parser context within

      handlers, you should not use this method to create a Docstring.
      Instead, use the {parser}, which takes a handler object that
      can pass parser state onto directives. If a Docstring is created
      with this method, directives do not have access to any parser
      state, and may not function as expected.

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

new!(text, tags = [], object = nil, raw_data = nil)

Creates a new docstring without performing any parsing through a {DocstringParser}. This method is called by `DocstringParser` when creating the new docstring object.

@param [String] text the textual portion of the docstring @param [Array<Tag>] tags the list of tag objects in the docstring @param [CodeObjects::Base, nil] object the object associated with the

      docstring. May be nil.

@param [String] raw_data the complete docstring, including all

      original formatting and any unparsed tags/directives.

parser(*args)

Creates a parser object using the current {default_parser}. Equivalent to:

      Docstring.default_parser.new(*args)

@param args arguments are passed to the {DocstringParser}

      class. See {DocstringParser#initialize} for details on
      arguments.

@return [DocstringParser] the parser object used to parse a

      docstring.

### 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 {DocstringParser} instead.

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

all=(content, parse = true)

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

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, parse = true)

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]