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   resolve_reference   summary   tag   tags   to_raw   to_s  

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.

@param [CodeObjects::Base, nil] ref_object a reference object used for

  the base set of documentation / tag information.

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

Resolves unresolved other docstring reference if there is unresolved reference. Does nothing if there is no unresolved reference.

Normally, you don‘t need to call this method explicitly. Resolving unresolved reference is done implicitly.

@return [void]

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]