search-and-deploy/_cheat-sheets/2018-03-18-rdoc.md

---

description: > Simple markup language documenting Ruby code.

title: "Rdoc"

Document Ruby code using simple comments.

Table of Contents

• TOC {:toc}

Markup

Headings

# = H1
# == H2

And so forth.

Paragraphs

# Paragraph
# Still Paragraph
#
# New Paragraph
#
#   this.will.be(verbatim)

Inline modifiers

Inline text modifiers.

| HTML | RDoc | |-----------------|----------| | `text` | `_text_` | | `text` | `*text*` | | `text` | `+word+` |

Precede first control-char with \ to escape it.

Links

Classes, source files, and method names are linked automatically using plain text Eg. http:, mailto:, ftp:, and www. prefixes.

Images are turned into <img>s automatically.

Use link:asd/asd.html for links relative to -op dir.

Labeled links with either one of:

label[url]
{multi word label}[url]

Lists

Lists are typed as indented paragraphs with:

# Regular paragraph
#   * bullet list
#   - bullet list
#   1. numbered list a. alpha list
#   A. alpha list

Labeled Lists

# [cat] small domestic animal
# [+cat+] command to copy standard input

For tabular format:

# cat::   small domestic animal
#         indent the second line
# +cat+:: command to copy standard input
#   you don't have to indent all the
#   way though

Horizontal Rules

# --- or more hyphens

Doc Modifiers

Method calls

Beginning of method comment call-seq:.

# call-seq:
#   function(arg1,arg2) => result
#   function(arg1, arg2, arg3) => res
#
# Begin description

Stop Comments

| Description | Modifier | |-----------------------------------------------|----------------------------| | omit documentation | `:nodoc:` / `:nodoc: all` | | Document nothing further at the current level | `:enddoc:` | | Toggle current scope documentation | `:stopdoc:` / `:startdoc:` | | alias toggle current scope documentation | `--` / `++` |

For example,

# rdoc Comment line
#--
# Not a rdoc comment
#++
# rdoc again

Yield arguments

Relabel yield arguments.

def fred # :yields: index, position
  yield line, address
end

Titles

# --------------------------------------
# :section: My Section
# This is the section that I wrote.
# --------------------------------------

Other modifiers

| Description | Modifier | |-----------------------------------------------|----------------------------| | Don't use initialize signature | `:notnew:` | | Insert file `filename` | `:include:filename` | | Set document title to `text` | `:title:text` | | Class `name` will appear on the index page | `:main:name` |

For more details read the official documentation{:rel="nofollow noreferrer noopener"}

Original by jan.varwig.org. Licensed under Creative Commons BY-SA.