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

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.

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.

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

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

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

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 all tags with name @param [String] name the tag name @return [void] @since 0.7.0

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

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} @return [nil] if there is no associated {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

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]