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

Subclassing Notes

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

Methods

Constants

META_MATCH = /^@(!)?((?:\w\.?)+)(?:\s+(.*))?$/i   The regular expression to match the tag syntax

Attributes

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.

Public Class methods

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]

@return [Array<Proc>] the {after_parse} callback proc objects

Creates a new parser to parse docstring data

@param [Tags::Library] library a tag library for recognizing

  tags.

Public Instance methods

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

Parses a given block of text.

@param [String] content the content to parse @note Subclasses can override this method to perform custom

  parsing of content data.

Backward compatibility to detect old tags that should be specified as directives in 0.8 and onward.

@return [Docstring] translates parsed text into

  a Docstring object.

[Validate]