Class | YARD::DocstringParser |
In: |
lib/yard/docstring_parser.rb
|
Parent: | Object |
Parses text and creates a {Docstring} object to represent documentation for a {CodeObjects::Base}. To create a new docstring, you should initialize the parser and call {parse} followed by {to_docstring}.
The DocstringParser can be subclassed and subtituted during parsing by setting the {Docstring.default_parser} attribute with the name of the subclass. This allows developers to change the way docstrings are parsed, allowing for completely different docstring syntaxes.
@example Creating a Docstring with a DocstringParser
DocstringParser.new.parse("text here").to_docstring
@example Creating a Custom DocstringParser
# Parses docstrings backwards! class ReverseDocstringParser def parse_content(content) super(content.reverse) end end # Set the parser as default when parsing YARD::Docstring.default_parser = ReverseDocstringParser
@see parse_content @since 0.8.0
META_MATCH | = | /^@(!)?((?:\w\.?)+)(?:\s+(.*))?$/i | The regular expression to match the tag syntax |
directives | [RW] |
@return [Array<Directive>] a list of
directives identified
by the parser. This list will not be passed on to the Docstring object. |
handler | [RW] |
@return [Handlers::Base, nil] the handler
parsing this
docstring. May be nil if this docstring parser is not initialized through |
library | [RW] |
@return [Tags::Library] the tag library
being used to
identify registered tags in the docstring. |
object | [RW] |
@return [CodeObjects::Base, nil] the
object associated with
the docstring being parsed. May be nil if the docstring is not attached to any object. |
raw_text | [RW] | @return [String] the complete input string to the parser. |
state | [RW] |
@return [OpenStruct] any arbitrary state to be passed between
tags during parsing. Mainly used by directives to coordinate behaviour (so that directives can be aware of other directives used in a docstring). |
tags | [RW] |
@return [Array<Tag>] the list of
meta-data tags identified
by the parser |
text | [RW] |
@return [String] the parsed text portion of
the docstring,
with tags removed. |
Creates a callback that is called after a docstring is successfully parsed. Use this method to perform sanity checks on a docstring‘s tag data, or add any extra tags automatically to a docstring.
@yield [parser] a block to be called after a docstring is parsed @yieldparam [DocstringParser] parser the docstring parser object
with all directives and tags created.
@yieldreturn [void] @return [void]
Creates a new parser to parse docstring data
@param [Tags::Library] library a tag library for recognizing
tags.
Creates a new directive using the registered {library} @return [Directive] the directive object that is created
Creates a tag from the {Tags::DefaultFactory tag factory}.
To add an already created tag object, append it to {tags}.
@param [String] tag_name the tag name @param [String] tag_buf the text attached to the tag with newlines removed. @return [Tags::Tag, Tags::RefTag] a tag
Parses all content and returns itself.
@param [String] content the docstring text to parse @param [CodeObjects::Base] object the object that the docstring
is attached to. Will be passed to directives to act on this object.
@param [Handlers::Base, nil] handler the handler object that is
parsing this object. May be nil if this parser is not being called from a {Parser::SourceParser} context.
@return [self] the parser object. To get the docstring,
call {#to_docstring}.
@see to_docstring