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