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?   has_tag?   hash_flag=   line   new   replace   summary   tag   tags  

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

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

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

Adds a tag or reftag object to the tag list @param [Tags::Tag, Tags::RefTag] tags list of tag objects to add

all=(content)

Alias for replace

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

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

@return [Fixnum] the first line of the {line_range}.

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

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.

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}

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

[Validate]