require 'rdoc'
# \Class \RDoc::MarkupReference exists only to provide a suitable home
# for a reference document for \RDoc markup.
#
# All objects defined in this class -- classes, modules, methods, aliases,
# attributes, and constants -- are solely for illustrating \RDoc markup,
# and have no other legitimate use.
#
# = \RDoc Markup Reference
#
# Notes:
#
# - Examples in this reference are Ruby code and comments;
# certain differences from other sources
# (such as C code and comments) are noted.
# - An example that shows rendered HTML output
# displays that output in a blockquote:
#
# Rendered HTML:
# >>>
# Some stuff
#
# \RDoc-generated documentation is derived from and controlled by:
#
# - Single-line or multi-line comments that precede certain definitions;
# see {Markup in Comments}[rdoc-ref:RDoc::MarkupReference@Markup+in+Comments].
# - \RDoc directives in trailing comments (on the same line as code);
# see :nodoc:, :doc:, and :notnew:.
# - \RDoc directives in single-line comments;
# see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives].
# - The Ruby code itself (but not from C code);
# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code].
#
# == Markup in Comments
#
# The treatment of markup in comments varies according to the type of file:
#
# - .rb (Ruby code file): markup is parsed from Ruby comments.
# - .c (C code file): markup is parsed from C comments.
# - .rdoc (RDoc text file): markup is parsed from the entire file.
#
# The comment associated with
# a Ruby class, module, method, alias, constant, or attribute
# becomes the documentation for that defined object:
#
# - In a Ruby file, that comment immediately precedes
# the definition of the object.
# - In a C file, that comment immediately precedes
# the function that implements a method,
# or otherwise immediately precedes the definition of the object.
#
# In either a Ruby or a C file,
# \RDoc ignores comments that do not precede object definitions.
#
# In an \RDoc file, the text is not associated with any code object,
# but may (depending on how the documentation is built),
# become a separate page.
#
# Almost all examples on this page are all RDoc-like;
# that is, they have no comment markers like Ruby #
# or C /* ... */.
#
# === Margins
#
# In a multi-line comment,
# \RDoc looks for the comment's natural left margin,
# which becomes the base margin for the comment
# and is the initial current margin for the comment.
#
# The current margin can change, and does so, for example in a list.
#
# === Blocks
#
# It's convenient to think of \RDoc markup input as a sequence of _blocks_
# of various types (details at the links):
#
# - {Paragraph}[rdoc-ref:RDoc::MarkupReference@Paragraphs]:
# an ordinary paragraph.
# - {Verbatim text block}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks]:
# a block of text to be rendered literally.
# - {Code block}[rdoc-ref:RDoc::MarkupReference@Code+Blocks]:
# a verbatim text block containing Ruby code,
# to be rendered with code highlighting.
# - {Block quote}[rdoc-ref:RDoc::MarkupReference@Block+Quotes]:
# a longish quoted passage, to be rendered with indentation
# instead of quote marks.
# - {List}[rdoc-ref:RDoc::MarkupReference@Lists]: items for
# a bullet list, numbered list, lettered list, or labeled list.
# - {Heading}[rdoc-ref:RDoc::MarkupReference@Headings]:
# a section heading.
# - {Horizontal rule}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules]:
# a line across the rendered page.
# - {Directive}[rdoc-ref:RDoc::MarkupReference@Directives]:
# various special directions for the rendering.
# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup]:
# text to be rendered in a special way.
#
# About the blocks:
#
# - Except for a paragraph, a block is distinguished by its indentation,
# or by unusual initial or embedded characters.
# - Any block may appear independently
# (that is, not nested in another block);
# some blocks may be nested, as detailed below.
#
# ==== Paragraphs
#
# A paragraph consists of one or more non-empty lines of ordinary text,
# each beginning at the current margin.
#
# Note: Here, ordinary text means text that is not identified
# by indentation, or by unusual initial or embedded characters.
# See below.
#
# Paragraphs are separated by one or more empty lines.
#
# Example input:
#
# \RDoc produces HTML and command-line documentation for Ruby projects.
# \RDoc includes the rdoc and ri tools for generating and displaying
# documentation from the command-line.
#
# You'll love it.
#
# Rendered HTML:
# >>>
# \RDoc produces HTML and command-line documentation for Ruby projects.
# \RDoc includes the rdoc and ri tools for generating and displaying
# documentation from the command-line.
#
# You'll love it.
#
# A paragraph may contain nested blocks, including:
#
# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks].
# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks].
# - {Block quotes}[rdoc-ref:RDoc::MarkupReference@Block+Quotes].
# - {Lists}[rdoc-ref:RDoc::MarkupReference@Lists].
# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings].
# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules].
# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
#
# ==== Verbatim Text Blocks
#
# Text indented farther than the current margin becomes a verbatim text block
# (or a code block, described next).
# In the rendered HTML, such text:
#
# - Is indented.
# - Has a contrasting background color.
#
# The verbatim text block ends at the first line beginning at the current margin.
#
# Example input:
#
# This is not verbatim text.
#
# This is verbatim text.
# Whitespace is honored. # See?
# Whitespace is honored. # See?
#
# This is still the same verbatim text block.
#
# This is not verbatim text.
#
# Rendered HTML:
# >>>
# This is not verbatim text.
#
# This is verbatim text.
# Whitespace is honored. # See?
# Whitespace is honored. # See?
#
# This is still the same verbatim text block.
#
# This is not verbatim text.
#
# A verbatim text block may not contain nested blocks of any kind
# -- it's verbatim.
#
# ==== Code Blocks
#
# A special case of verbatim text is the code block,
# which is merely verbatim text that \RDoc recognizes as Ruby code:
#
# In the rendered HTML, the code block:
#
# - Is indented.
# - Has a contrasting background color.
# - Has syntax highlighting.
#
# Example input:
#
# Consider this method:
#
# def foo(name = '', value = 0)
# @name = name # Whitespace is still honored.
# @value = value
# end
#
#
# Rendered HTML:
# >>>
# Consider this method:
#
# def foo(name = '', value = 0)
# @name = name # Whitespace is still honored.
# @value = value
# end
#
# Pro tip: If your indented Ruby code does not get highlighted,
# it may contain a syntax error.
#
# A code block may not contain nested blocks of any kind
# -- it's verbatim.
#
# ==== Block Quotes
#
# You can use the characters >>> (unindented),
# followed by indented text, to treat the text
# as a {block quote}[https://en.wikipedia.org/wiki/Block_quotation]:
#
# Example input:
#
# Here's a block quote:
# >>>
# Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
# commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
# Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.
#
# Aenean congue ligula eu ligula molestie, eu pellentesque purus
# faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum,
# diam in pellentesque aliquet, mi tellus placerat sapien, id euismod
# purus magna ut tortor.
#
# Rendered HTML:
#
# >>>
# Here's a block quote:
# >>>
# Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
# commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
# Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.
#
# Aenean congue ligula eu ligula molestie, eu pellentesque purus
# faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum,
# diam in pellentesque aliquet, mi tellus placerat sapien, id euismod
# purus magna ut tortor.
#
# Note that, unlike verbatim text, single newlines are not honored,
# but that a double newline begins a new paragraph in the block quote.
#
# A block quote may contain nested blocks, including:
#
# - Other block quotes.
# - {Paragraphs}[rdoc-ref:RDoc::MarkupReference@Paragraphs].
# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks].
# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks].
# - {Lists}[rdoc-ref:RDoc::MarkupReference@Lists].
# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings].
# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules].
# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
#
# ==== Lists
#
# Each type of list item is marked by a special beginning:
#
# - Bullet list item: Begins with a hyphen or asterisk.
# - Numbered list item: Begins with digits and a period.
# - Lettered list item: Begins with an alphabetic character and a period.
# - Labeled list item: Begins with one of:
# - Square-bracketed text.
# - A word followed by two colons.
#
# A list begins with a list item and continues, even across blank lines,
# as long as list items of the same type are found at the same indentation level.
#
# A new list resets the current margin inward.
# Additional lines of text aligned at that margin
# are part of the continuing list item.
#
# A list item may be continued on additional lines that are aligned
# with the first line. See examples below.
#
# A list item may contain nested blocks, including:
#
# - Other lists of any type.
# - {Paragraphs}[rdoc-ref:RDoc::MarkupReference@Paragraphs].
# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks].
# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks].
# - {Block quotes}[rdoc-ref:RDoc::MarkupReference@Block+Quotes].
# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings].
# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules].
# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
#
# ===== Bullet Lists
#
# A bullet list item begins with a hyphen or asterisk.
#
# Example input:
#
# - An item.
# - Another.
# - An item spanning
# multiple lines.
#
# * Yet another.
# - Last one.
#
# Rendered HTML:
# >>>
# - An item.
# - Another.
# - An item spanning
# multiple lines.
#
# * Yet another.
# - Last one.
#
# ===== Numbered Lists
#
# A numbered list item begins with digits and a period.
#
# The items are automatically re-numbered.
#
# Example input:
#
# 100. An item.
# 10. Another.
# 1. An item spanning
# multiple lines.
#
# 1. Yet another.
# 1000. Last one.
#
# Rendered HTML:
# >>>
# 100. An item.
# 10. Another.
# 1. An item spanning
# multiple lines.
#
# 1. Yet another.
# 1000. Last one.
#
# ===== Lettered Lists
#
# A lettered list item begins with letters and a period.
#
# The items are automatically "re-lettered."
#
# Example input:
#
# z. An item.
# y. Another.
# x. An item spanning
# multiple lines.
#
# x. Yet another.
# a. Last one.
#
# Rendered HTML:
# >>>
# z. An item.
# y. Another.
#
# x. Yet another.
# a. Last one.
#
# ===== Labeled Lists
#
# A labeled list item begins with one of:
#
# - Square-bracketed text: the label and text are on two lines.
# - A word followed by two colons: the label and text are on the same line.
#
# Example input:
#
# [foo] An item.
# bat:: Another.
# [bag] An item spanning
# multiple lines.
#
# [bar baz] Yet another.
# bam:: Last one.
#
# Rendered HTML:
# >>>
# [foo] An item.
# bat:: Another.
# [bag] An item spanning
# multiple lines.
#
# [bar baz] Yet another.
# bam:: Last one.
#
# ==== Headings
#
# A heading begins with up to six equal-signs, followed by heading text.
# Whitespace between those and the heading text is optional.
#
# Examples:
#
# = Section 1
# == Section 1.1
# === Section 1.1.1
# === Section 1.1.2
# == Section 1.2
# = Section 2
# = Foo
# == Bar
# === Baz
# ==== Bam
# ===== Bat
# ====== Bad
# ============Still a Heading (Level 6)
# \== Not a Heading
#
# A heading may contain only one type of nested block:
#
# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
#
# ==== Horizontal Rules
#
# A horizontal rule consists of a line with three or more hyphens
# and nothing more.
#
# Example input:
#
# ---
# --- Not a horizontal rule.
#
# -- Also not a horizontal rule.
# ---
#
# Rendered HTML:
# >>>
# ---
# --- Not a horizontal rule.
#
# -- Also not a horizontal rule.
# ---
#
# ==== Directives
#
# ===== Directives for Allowing or Suppressing Documentation
#
# - # :stopdoc::
#
# - Appears on a line by itself.
# - Specifies that \RDoc should ignore markup
# until next :startdoc: directive or end-of-file.
#
# - # :startdoc::
#
# - Appears on a line by itself.
# - Specifies that \RDoc should resume parsing markup.
#
# - # :enddoc::
#
# - Appears on a line by itself.
# - Specifies that \RDoc should ignore markup to end-of-file
# regardless of other directives.
#
# - # :nodoc::
#
# - Appended to a line of code
# that defines a class, module, method, alias, constant, or attribute.
# - Specifies that the defined object should not be documented.
#
# - # :nodoc: all:
#
# - Appended to a line of code
# that defines a class or module.
# - Specifies that the class or module should not be documented.
# By default, however, a nested class or module _will_ be documented.
#
# - # :doc::
#
# - Appended to a line of code
# that defines a class, module, method, alias, constant, or attribute.
# - Specifies the defined object should be documented, even if otherwise
# would not be documented.
#
# - # :notnew: (aliased as :not_new: and :not-new:):
#
# - Appended to a line of code
# that defines instance method +initialize+.
# - Specifies that singleton method +new+ should not be documented.
# By default, Ruby fakes a corresponding singleton method +new+,
# which \RDoc includes in the documentation.
# Note that instance method +initialize+ is private, and so by default
# is not documented.
#
# For Ruby code, but not for other \RDoc sources,
# there is a shorthand for :stopdoc: and :startdoc::
#
# # Documented.
# #--
# # Not documented.
# #++
# # Documented.
#
# For C code, any of directives :startdoc:, :enddoc:,
# and :nodoc: may appear in a stand-alone comment:
#
# /* :startdoc: */
# /* :stopdoc: */
# /* :enddoc: */
#
# ===== Directive for Specifying \RDoc Source Format
#
# - # :markup: _type_:
#
# - Appears on a line by itself.
# - Specifies the format for the \RDoc input;
# parameter +type+ is one of +markdown+, +rd+, +rdoc+, +tomdoc+.
#
# ===== Directives for HTML Output
#
# - # :title: _text_:
#
# - Appears on a line by itself.
# - Specifies the title for the HTML output.
#
# - # :main: _filename_:
# - Appears on a line by itself.
# - Specifies the HTML file to be displayed first.
#
# ===== Directives for Method Documentation
#
# - # :call-seq::
#
# - Appears on a line by itself.
# - Specifies the calling sequence to be reported in the HTML,
# overriding the actual calling sequence in the code.
# See method #call_seq_directive.
#
# Note that \RDoc can build the calling sequence for a Ruby-coded method,
# but not for other languages.
# You may want to override that by explicitly giving a :call-seq:
# directive if you want to include:
#
# - A return type, which is not automatically inferred.
# - Multiple calling sequences.
#
# For C code, the directive may appear in a stand-alone comment.
#
# - # :args: _arg_names_ (aliased as :arg:):
#
# - Appears on a line by itself.
# - Specifies the arguments to be reported in the HTML,
# overriding the actual arguments in the code.
# See method #args_directive.
#
# - # :yields: _arg_names_ (aliased as :yield:):
#
# - Appears on a line by itself.
# - Specifies the yield arguments to be reported in the HTML,
# overriding the actual yield in the code.
# See method #yields_directive.
#
# ===== Directives for Organizing Documentation
#
# By default, \RDoc groups:
#
# - Singleton methods together in alphabetical order.
# - Instance methods and their aliases together in alphabetical order.
# - Attributes and their aliases together in alphabetical order.
#
# You can use directives to modify those behaviors.
#
# - # :section: _section_title_:
#
# - Appears on a line by itself.
# - Specifies that following methods are to be grouped into the section
# with the given section_title,
# or into the default section if no title is given.
# The directive remains in effect until another such directive is given,
# but may be temporarily overridden by directive :category:.
# See below.
#
# The comment block containing this directive:
#
# - Must be separated by a blank line from the documentation for the next item.
# - May have one or more lines preceding the directive.
# These will be removed, along with any trailing lines that match them.
# Such lines may be visually helpful.
# - Lines of text that are not so removed become the descriptive text
# for the section.
#
# Example:
#
# # ----------------------------------------
# # :section: My Section
# # This is the section that I wrote.
# # See it glisten in the noon-day sun.
# # ----------------------------------------
#
# ##
# # Comment for some_method
# def some_method
# # ...
# end
#
# You can use directive :category: to temporarily
# override the current section.
#
# - # :category: _section_title_:
#
# - Appears on a line by itself.
# - Specifies that just one following method is to be included
# in the given section, or in the default section if no title is given.
# Subsequent methods are to be grouped into the current section.
#
# ===== Directive for Including a File
#
# - # :include: _filepath_:
#
# - Appears on a line by itself.
# - Specifies that the contents of the given file
# are to be included at this point.
# The file content is shifted to have the same indentation as the colon
# at the start of the directive.
#
# The file is searched for in the directories
# given with the --include command-line option,
# or by default in the current directory.
#
# For C code, the directive may appear in a stand-alone comment
#
# ==== Text Markup
#
# Text markup is metatext that affects HTML rendering:
#
# - Typeface: italic, bold, monofont.
# - Character conversions: copyright, trademark, certain punctuation.
# - Links.
# - Escapes: marking text as "not markup."
#
# ===== Typeface Markup
#
# Typeface markup can specify that text is to be rendered
# as italic, bold, or monofont.
#
# Typeface markup may contain only one type of nested block:
#
# - More typeface markup:
# italic, bold, monofont.
#
# ====== Italic
#
# Text may be marked as italic via HTML tag or .
#
# Example input:
#
# Italicized words in a paragraph.
#
# >>>
# Italicized words in a block quote.
#
# - Italicized words in a list item.
#
# ====== Italicized words in a Heading
#
# Italicized passage containing *bold* and +monofont+.
#
# Rendered HTML:
# >>>
# Italicized words in a paragraph.
#
# >>>
# Italicized words in a block quote.
#
# - Italicized words in a list item.
#
# ====== Italicized words in a Heading
#
# Italicized passage containing *bold* and +monofont+.
#
# A single word may be italicized via a shorthand:
# prefixed and suffixed underscores.
#
# Example input:
#
# _Italic_ in a paragraph.
#
# >>>
# _Italic_ in a block quote.
#
# - _Italic_ in a list item.
#
# ====== _Italic_ in a Heading
#
# Rendered HTML:
# >>>
# _Italic_ in a paragraph.
#
# >>>
# _Italic_ in a block quote.
#
# - _Italic_ in a list item.
#
# ====== _Italic_ in a Heading
#
# ====== Bold
#
# Text may be marked as bold via HTML tag .
#
# Example input:
#
# Bold words in a paragraph.
#
# >>>
# Bold words in a block quote.
#
# - Bold words in a list item.
#
# ====== Bold words in a Heading
#
# Bold passage containing _italics_ and +monofont+.
#
# Rendered HTML:
#
# >>>
# Bold words in a paragraph.
#
# >>>
# Bold words in a block quote.
#
# - Bold words in a list item.
#
# ====== Bold words in a Heading
#
# Bold passage containing _italics_ and +monofont+.
#
# A single word may be made bold via a shorthand:
# prefixed and suffixed asterisks.
#
# Example input:
#
# *Bold* in a paragraph.
#
# >>>
# *Bold* in a block quote.
#
# - *Bold* in a list item.
#
# ===== *Bold* in a Heading
#
# Rendered HTML:
#
# >>>
# *Bold* in a paragraph.
#
# >>>
# *Bold* in a block quote.
#
# - *Bold* in a list item.
#
# ===== *Bold* in a Heading
#
# ====== Monofont
#
# Text may be marked as monofont
# -- sometimes called 'typewriter font' --
# via HTML tag or
.
#
# Example input:
#
# Monofont words in a paragraph.
#
# >>>
# Monofont words in a block quote.
#
# - Monofont words in a list item.
#
# ====== Monofont words in heading
#
# Monofont passage containing _italics_ and *bold*.
#
# Rendered HTML:
#
# >>>
# Monofont words in a paragraph.
#
# >>>
# Monofont words in a block quote.
#
# - Monofont words in a list item.
#
# ====== Monofont words in heading
#
# Monofont passage containing _italics_ and *bold*.
#
# A single word may be made monofont by a shorthand:
# prefixed and suffixed plus-signs.
#
# Example input:
#
# +Monofont+ in a paragraph.
#
# >>>
# +Monofont+ in a block quote.
#
# - +Monofont+ in a list item.
#
# ====== +Monofont+ in a Heading
#
# Rendered HTML:
#
# >>>
# +Monofont+ in a paragraph.
#
# >>>
# +Monofont+ in a block quote.
#
# - +Monofont+ in a list item.
#
# ====== +Monofont+ in a Heading
#
# ==== Character Conversions
#
# Certain combinations of characters may be converted to special characters;
# whether the conversion occurs depends on whether the special character
# is available in the current encoding.
#
# - (c) converts to (c) (copyright character); must be lowercase.
#
# - (r) converts to (r) (registered trademark character); must be lowercase.
#
# - 'foo' converts to 'foo' (smart single-quotes).
#
# - "foo" converts to "foo" (smart double-quotes).
#
# - foo ... bar converts to foo ... bar (1-character ellipsis).
#
# - foo -- bar converts to foo -- bar (1-character en-dash).
#
# - foo --- bar converts to foo --- bar (1-character em-dash).
#
# ==== Links
#
# Certain strings in \RDoc text are converted to links.
# Any such link may be suppressed by prefixing a backslash.
# This section shows how to link to various
# targets.
#
# [Class]
#
# - On-page: DummyClass links to DummyClass.
# - Off-page: RDoc::Alias links to RDoc::Alias.
#
# [Module]
#
# - On-page: DummyModule links to DummyModule.
# - Off-page: RDoc links to RDoc.
#
# [Constant]
#
# - On-page: DUMMY_CONSTANT links to DUMMY_CONSTANT.
# - Off-page: RDoc::Text::MARKUP_FORMAT links to RDoc::Text::MARKUP_FORMAT.
#
# [Singleton Method]
#
# - On-page: ::dummy_singleton_method links to ::dummy_singleton_method.
# - Off-pageRDoc::TokenStream::to_html links to RDoc::TokenStream::to_html.
#
# Note: Occasionally \RDoc is not linked to a method whose name
# has only special characters. Check whether the links you were expecting
# are actually there. If not, you'll need to put in an explicit link;
# see below.
#
# Pro tip: The link to any method is available in the alphabetical table of contents
# at the top left of the page for the class or module.
#
# [Instance Method]
#
# - On-page: #dummy_instance_method links to #dummy_instance_method.
# - Off-page: RDoc::Alias#html_name links to RDoc::Alias#html_name.
#
# See the Note and Pro Tip immediately above.
#
# [Attribute]
#
# - On-page: #dummy_attribute links to #dummy_attribute.
# - Off-page: RDoc::Alias#name links to RDoc::Alias#name.
#
# [Alias]
#
# - On-page: #dummy_instance_alias links to #dummy_instance_alias.
# - Off-page: RDoc::Alias#new_name links to RDoc::Alias#new_name.
#
# [Protocol +http+]
#
# - Linked: http://yahoo.com links to http://yahoo.com.
#
# [Protocol +https+]
#
# - Linked: https://github.com links to https://github.com.
#
# [Protocol +www+]
#
# - Linked: www.yahoo.com links to www.yahoo.com.
#
# [Protocol +ftp+]
#
# - Linked: ftp://nosuch.site links to ftp://nosuch.site.
#
# [Protocol +mailto+]
#
# - Linked: mailto:/foo@bar.com links to mailto://foo@bar.com.
#
# [Protocol +irc+]
#
# - link: irc://irc.freenode.net/ruby links to irc://irc.freenode.net/ruby.
#
# [Image Filename Extensions]
#
# - Link: https://www.ruby-lang.org/images/header-ruby-logo@2x.png is
# converted to an in-line HTML +img+ tag, which displays the image in the HTML:
#
# https://www.ruby-lang.org/images/header-ruby-logo@2x.png
#
# Also works for +bmp+, +gif+, +jpeg+, and +jpg+ files.
#
# Note: Works only for a fully qualified URL.
#
# [Heading]
#
# - Link: RDoc::RD@LICENSE links to RDoc::RDoc::RD@LICENSE.
#
# Note that spaces in the actual heading are represented by + characters
# in the linkable text.
#
# - Link: RDoc::Options@Saved+Options
# links to RDoc::Options@Saved+Options.
#
# Punctuation and other special characters must be escaped like CGI.escape.
#
# Pro tip: The link to any heading is available in the alphabetical table of contents
# at the top left of the page for the class or module.
#
# [Section]
#
# See {Directives for Organizing Documentation}[#class-RDoc::MarkupReference-label-Directives+for+Organizing+Documentation].
#
# - Link: RDoc::Markup::ToHtml@Visitor links to RDoc::Markup::ToHtml@Visitor.
#
# If a section and a heading share the same name, the link target is the section.
#
# [Single-Word Text Link]
#
# Use square brackets to create single-word text link:
#
# - GitHub[https://github.com] links to GitHub[https://github.com].
#
# [Multi-Word Text Link]
#
# Use square brackets and curly braces to create a multi-word text link.
#
# - {GitHub home page}[https://github.com] links to
# {GitHub home page}[https://github.com].
#
# [rdoc-ref Scheme]
#
# A link with the rdoc-ref: scheme links to the referenced item,
# if that item exists.
# The referenced item may be a class, module, method, file, etc.
#
# - Class: Alias[rdoc-ref:RDoc::Alias] links to Alias[rdoc-ref:RDoc::Alias].
# - Module: RDoc[rdoc-ref:RDoc] links to RDoc[rdoc-ref:RDoc].
# - Method: foo[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK]
# links to foo[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK].
# - Constant: bar[rdoc-ref:RDoc::Markup::ToHtml::LIST_TYPE_TO_HTML]
# links to bar[rdoc-ref:RDoc::Markup::ToHtml::LIST_TYPE_TO_HTML].
# - Attribute: baz[rdoc-ref:RDoc::Markup::ToHtml#code_object]
# links to baz[rdoc-ref:RDoc::Markup::ToHtml#code_object].
# - Alias: bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias] links to
# bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias].
#
# If the referenced item does not exist, no link is generated
# and entire rdoc-ref: square-bracketed clause is removed
# from the resulting text.
#
# - Nosuch[rdoc-ref:RDoc::Nosuch] is rendered as
# Nosuch[rdoc-ref:RDoc::Nosuch].
#
#
# [rdoc-label Scheme]
#
# [Simple]
#
# You can specify a link target using this form,
# where the second part cites the id of an HTML element.
#
# This link refers to the constant +DUMMY_CONSTANT+ on this page:
#
# - {DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT]
#
# Thus:
#
# {DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT]
#
# [With Return]
#
# You can specify both a link target and a local label
# that can be used as the target for a return link.
# These two links refer to each other:
#
# - {go to addressee}[rdoc-label:addressee:sender]
# - {return to sender}[rdoc-label:sender:addressee]
#
# Thus:
#
# {go to addressee}[rdoc-label:addressee:sender]
#
# Some text.
#
# {return to sender}[rdoc-label:sender:addressee]
#
# [link: Scheme]
#
# - link:README_rdoc.html links to link:README_rdoc.html.
#
# [rdoc-image Scheme]
#
# Use the rdoc-image scheme to display an image that is also a link:
#
# # {rdoc-image:path/to/image}[link_target]
#
# - Link: {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[https://www.ruby-lang.org]
# displays image https://www.ruby-lang.org/images/header-ruby-logo@2x.png
# as a link to https://www.ruby-lang.org.
#
# {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[https://www.ruby-lang.org]
#
# A relative path as the target also works:
#
# - Link: {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html] links to ./Alias.html
#
# {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html]
#
# === Escaping Text
#
# Text that would otherwise be interpreted as markup
# can be "escaped," so that it is not interpreted as markup;
# the escape character is the backslash ('\\').
#
# In a verbatim text block or a code block,
# the escape character is always preserved:
#
# Example input:
#
# This is not verbatim text.
#
# This is verbatim text, with an escape character \.
#
# This is not a code block.
#
# def foo
# 'String with an escape character.'
# end
#
# Rendered HTML:
#
# >>>
# This is not verbatim text.
#
# This is verbatim text, with an escape character \.
#
# This is not a code block.
#
# def foo
# 'This is a code block with an escape character \.'
# end
#
# In typeface markup (italic, bold, or monofont),
# an escape character is preserved unless it is immediately
# followed by nested typeface markup.
#
# Example input:
#
# This list is about escapes; it contains:
#
# - Monofont text with unescaped nested _italic_.
# - Monofont text with escaped nested \_italic_.
# - Monofont text with an escape character \.
#
# Rendered HTML:
#
# >>>
# This list is about escapes; it contains:
#
# - Monofont text with unescaped nested _italic_.
# - Monofont text with escaped nested \_italic_.
# - Monofont text with an escape character \ .
#
# In other text-bearing blocks
# (paragraphs, block quotes, list items, headings):
#
# - A single escape character immediately followed by markup
# escapes the markup.
# - A single escape character followed by whitespace is preserved.
# - A single escape character anywhere else is ignored.
# - A double escape character is rendered as a single backslash.
#
# Example input:
#
# This list is about escapes; it contains:
#
# - An unescaped class name, RDoc, that will become a link.
# - An escaped class name, \RDoc, that will not become a link.
# - An escape character followed by whitespace \ .
# - An escape character \that is ignored.
# - A double escape character \\ that is rendered
# as a single backslash.
#
# Rendered HTML:
#
# >>>
# This list is about escapes; it contains:
#
# - An unescaped class name, RDoc, that will become a link.
# - An escaped class name, \RDoc, that will not become a link.
# - An escape character followed by whitespace \ .
# - An escape character \that is ignored.
# - A double escape character \\ that is rendered
# as a single backslash.
#
# == Documentation Derived from Ruby Code
#
# [Class]
#
# By default, \RDoc documents:
#
# - \Class name.
# - Parent class.
# - Singleton methods.
# - Instance methods.
# - Aliases.
# - Constants.
# - Attributes.
#
# [Module]
#
# By default, \RDoc documents:
#
# - \Module name.
# - \Singleton methods.
# - Instance methods.
# - Aliases.
# - Constants.
# - Attributes.
#
# [Method]
#
# By default, \RDoc documents:
#
# - \Method name.
# - Arguments.
# - Yielded values.
#
# See #method.
#
# [Alias]
#
# By default, \RDoc documents:
#
# - Alias name.
# - Aliased name.
#
# See #dummy_instance_alias and #dummy_instance_method.
#
# [Constant]
#
# By default, \RDoc documents:
#
# - \Constant name.
#
# See DUMMY_CONSTANT.
#
# [Attribute]
#
# By default, \RDoc documents:
#
# - Attribute name.
# - Attribute type ([R], [W], or [RW])
#
# See #dummy_attribute.
#
class RDoc::MarkupReference
class DummyClass; end
module DummyModule; end
def self.dummy_singleton_method(foo, bar); end
def dummy_instance_method(foo, bar); end;
alias dummy_instance_alias dummy_instance_method
attr_accessor :dummy_attribute
alias dummy_attribute_alias dummy_attribute
DUMMY_CONSTANT = ''
# :call-seq:
# call_seq_directive(foo, bar)
# Can be anything -> bar
# Also anything more -> baz or bat
#
# The :call-seq: directive overrides the actual calling sequence
# found in the Ruby code.
#
# - It can specify anything at all.
# - It can have multiple calling sequences.
#
# This one includes Can be anything -> foo, which is nonsense.
#
# Note that the "arrow" is two characters, hyphen and right angle-bracket,
# which is made into a single character in the HTML.
#
# Click on the calling sequence to see the code.
#
# Here is the :call-seq: directive given for the method:
#
# :call-seq:
# call_seq_directive(foo, bar)
# Can be anything -> bar
# Also anything more -> baz or bat
#
def call_seq_directive
nil
end
# The :args: directive overrides the actual arguments found in the Ruby code.
#
# Click on the calling sequence to see the code.
#
def args_directive(foo, bar) # :args: baz
nil
end
# The :yields: directive overrides the actual yield found in the Ruby code.
#
# Click on the calling sequence to see the code.
#
def yields_directive(foo, bar) # :yields: 'bat'
yield 'baz'
end
# This method is documented only by \RDoc, except for these comments.
#
# Click on the calling sequence to see the code.
#
def method(foo, bar)
yield 'baz'
end
end