RDoc::TomDoc

A parser for TomDoc based on TomDoc 1.0.0-rc1 (02adef9b5a)

The TomDoc specification can be found at:

The latest version of the TomDoc specification can be found at:

github.com/mojombo/tomdoc/blob/master/tomdoc.md

To choose TomDoc as your only default format see Saved Optionsfor at RDoc::Options instructions on setting up a .rdoc_options file to storeyour project default.

There are a few differences between this parser and the specification. Abest-effort was made to follow the specification as closely as possible butsome choices to deviate were made.

A future version of RDoc will warn when a MUST or MUST NOT is violated andmay warn when a SHOULD or SHOULD NOT is violated. RDoc will always tryto emit documentation even if given invalid TomDoc.

Here are some implementation choices this parser currently makes:

This parser allows rdoc-style inline markup but you should not depended onit.

This parser allows a space between the comment and the method body.

This parser does not require the default value to be described for anoptional argument.

This parser does not examine the order of sections. An Examples section mayprecede the Arguments section.

This class is documented in TomDoc format. Since this is a subclass of theRDoc markup parser there isn’t much to see here, unfortunately.

Public ↑ top

Public Class Methods

new() click to toggle source

Creates a new TomDoc parser. See also RDoc::Markup.parse

 
               # File rdoc/tom_doc.rb, line 129
def initialize
  super

  @section = nil
end

parse(text) click to toggle source

Parses TomDoc from text

text: A String containing TomDoc-format text.

Examples¶ ↑

RDoc::TomDoc.parse <<-TOMDOC
This method does some things

Returns nothing.
TOMDOC
# => #<RDoc::Markup::Document:0xXXX @parts=[...], @file=nil>

Returns an RDoc::Markup::Document representing the TomDoc format.

 
               # File rdoc/tom_doc.rb, line 83
def self.parse text
  parser = new

  parser.tokenize text
  doc = RDoc::Markup::Document.new
  parser.parse doc
  doc
end

Internal ↑ top

Attributes

tokens[R]

Token accessor

Public Class Methods

signature(comment) click to toggle source

Extracts the Signature section’s method signature

comment: An RDoc::Comment that will be parsed and have the signatureextracted

Returns a String containing the signature and nil if not

 
               # File rdoc/tom_doc.rb, line 99
def self.signature comment
  return unless comment.tomdoc?

  document = comment.parse

  signature = nil
  found_heading = false
  found_signature = false

  document.parts.delete_if do |part|
    next false if found_signature

    found_heading ||=
      RDoc::Markup::Heading === part && part.text == 'Signature'

    next false unless found_heading

    next true if RDoc::Markup::BlankLine === part

    if RDoc::Markup::Verbatim === part then
      signature = part
      found_signature = true
    end
  end

  signature and signature.text
end

Public Instance Methods

build_heading(level) click to toggle source

Builds a heading from the token stream

level: The level of heading to create

Returns an RDoc::Markup::Heading

 
               # File rdoc/tom_doc.rb, line 141
def build_heading level
  heading = super

  @section = heading.text

  heading
end

build_paragraph(margin) click to toggle source

Builds a paragraph from the token stream

margin: Unused

Returns an RDoc::Markup::Paragraph.

 
               # File rdoc/tom_doc.rb, line 171
def build_paragraph margin
  p :paragraph_start => margin if @debug

  paragraph = RDoc::Markup::Paragraph.new

  until @tokens.empty? do
    type, data, = get

    if type == :TEXT then
      paragraph << data
      skip :NEWLINE
    else
      unget
      break
    end
  end

  p :paragraph_end => margin if @debug

  paragraph
end

build_verbatim(margin) click to toggle source

Builds a verbatim from the token stream. A verbatim in theExamples section will be marked as in ruby format.

margin: The indentation from the margin for lines that belong to thisverbatim section.

Returns an RDoc::Markup::Verbatim

 
               # File rdoc/tom_doc.rb, line 157
def build_verbatim margin
  verbatim = super

  verbatim.format = :ruby if @section == 'Examples'

  verbatim
end

tokenize(text) click to toggle source

Turns text into an Array of tokens

text: A String containing TomDoc-format text.

Returns self.

 
               # File rdoc/tom_doc.rb, line 199
def tokenize text
  text.sub!(/\A(Public|Internal|Deprecated):\s+/, '')

  setup_scanner text

  until @s.eos? do
    pos = @s.pos

    # leading spaces will be reflected by the column of the next token
    # the only thing we loose are trailing spaces at the end of the file
    next if @s.scan(/ +/)

    @tokens << case
               when @s.scan(/\r?\n/) then
                 token = [:NEWLINE, @s.matched, *token_pos(pos)]
                 @line_pos = char_pos @s.pos
                 @line += 1
                 token
               when @s.scan(/(Examples|Signature)$/) then
                 @tokens << [:HEADER, 3, *token_pos(pos)]

                 [:TEXT, @s[1], *token_pos(pos)]
               when @s.scan(/([:\w][\w\[\]]*)[ ]+- /) then
                 [:NOTE, @s[1], *token_pos(pos)]
               else
                 @s.scan(/.*/)
                 [:TEXT, @s.matched.sub(/\r$/, ''), *token_pos(pos)]
               end
  end

  self
end

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please see Improve the docs, or visit Documenting-ruby.org.

Home Classes Methods

In Files

Parent

Sections

Methods

Class/Module Index

RDoc::TomDoc

Public ↑ top

Public Class Methods

Examples¶ ↑

Internal ↑ top

Attributes

Public Class Methods

Public Instance Methods