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.
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 |
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.
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]
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
@return [Fixnum] the first line of the {line_range} @return [nil] if there is no associated {line_range}