diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb new file mode 100644 index 0000000000..74594e5483 --- /dev/null +++ b/doc/rdoc/markup_reference.rb @@ -0,0 +1,916 @@ +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 +# +# [Note] +# +# Examples in this reference are Ruby code and comments. +# Certain differences among the sources are noted. +# +# \RDoc-generated documentation is derived from and controlled by: +# +# - Single-line or multi-line comments that precede certain definitions. +# - \RDoc directives in trailing comments (on the same line as code). +# - The Ruby code itself. +# +# == Markup in Comments +# +# A single-line or multi-line comment that immediately precedes +# the definition of a class, module, method, alias, constant, or attribute +# becomes the documentation for that defined object. +# +# (\RDoc ignores other such comments that do not precede definitions.) +# +# === 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 for the comment. +# +# The current margin can change, and does so, for example in a list. +# +# === Blocks +# +# It's convenient to think of markup input as a sequence of _blocks_, +# such as: +# +# - {Paragraphs}[rdoc-ref:RDoc::MarkupReference@Paragraphs]. +# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks]. +# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks]. +# - {Bullet lists}[rdoc-ref:RDoc::MarkupReference@Bullet+Lists]. +# - {Numbered lists}[rdoc-ref:RDoc::MarkupReference@Numbered+Lists]. +# - {Lettered lists}[rdoc-ref:RDoc::MarkupReference@Lettered+Lists]. +# - {Labeled lists}[rdoc-ref:RDoc::MarkupReference@Labeled+Lists]. +# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings]. +# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules]. +# - {Directives}[rdoc-ref:RDoc::MarkupReference@Directives]. +# +# All of these except paragraph blocks are distinguished by indentation, +# or by unusual initial or embedded characters. +# +# ==== 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. +# - Code blocks. +# - Lists of any type. +# +# ==== 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. +# ==== 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: +# +# 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. +# +# ==== 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. +# +# ===== 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 numbered list item begins with a 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. +# +# ===== Blocks Nested in Lists +# +# A list item may contain nested blocks, including: +# +# - Paragraphs. +# - Verbatim text blocks. +# - Code blocks. +# - Other lists of any type. +# +# ==== 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 +# +# ==== Horizontal Rules +# +# A horizontal rule begins with three or more hyphens. +# +# Example input: +# +# # ------ +# # Stuff between. +# # +# # \--- Not a horizontal rule. +# # +# # -- Also not a horizontal rule. +# # +# # --- +# +# Rendered HTML: +# +# ------ +# Stuff between. +# +# \--- Not a horizontal rule. +# +# -- Also not a horizontal rule. +# +# --- +# +# === Text Markup +# +# Text in a paragraph, list item (any type), or heading +# may have markup formatting. +# +# ==== Italic +# +# A single word may be italicized by prefixed and suffixed underscores. +# +# Examples: +# +# # _Word_ in paragraph. +# # - _Word_ in bullet list item. +# # 1. _Word_ in numbered list item. +# # a. _Word_ in lettered list item. +# # [_word_] _Word_ in labeled list item. +# # ====== _Word_ in heading +# +# Any text may be italicized via HTML tag +i+ or +em+. +# +# Examples: +# +# # Two words in paragraph. +# # - Two words in bullet list item. +# # 1. Two words in numbered list item. +# # a. Two words in lettered list item. +# # [Two words] Two words in labeled list item. +# # ====== Two words in heading +# +# ==== Bold +# +# A single word may be made bold by prefixed and suffixed asterisks. +# +# Examples: +# +# # *Word* in paragraph. +# # - *Word* in bullet list item. +# # 1. *Word* in numbered list item. +# # a. *Word* in lettered list item. +# # [*word*] *Word* in labeled list item. +# # ====== *Word* in heading +# +# Any text may be made bold via HTML tag +b+. +# +# Examples: +# +# # Two words in paragraph. +# # - Two words in bullet list item. +# # 1. Two words in numbered list item. +# # a. Two words in lettered list item. +# # [Two words] Two words in labeled list item. +# # ====== Two words in heading +# +# ==== Monofont +# +# A single word may be made monofont -- sometimes called "typewriter font" -- +# by prefixed and suffixed plus-signs. +# +# Examples: +# +# # +Word+ in paragraph. +# # - +Word+ in bullet list item. +# # 1. +Word+ in numbered list item. +# # a. +Word+ in lettered list item. +# # [+word+] +Word+ in labeled list item. +# # ====== +Word+ in heading +# +# Any text may be made monofont via HTML tag +tt+ or +code+. +# +# Examples: +# +# # Two words in paragraph. +# # - Two words in bullet list item. +# # 1. Two words in numbered list item. +# # a. Two words in lettered list item. +# # [Two words] Two words in labeled list item. +# # ====== Two words in 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. +# 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] +# +# === Directives +# +# ==== Directives for Allowing or Suppressing Documentation +# +# Each directive described in this section must appear on a line by itself. +# +# - [:stopdoc:] +# Specifies that \RDoc should ignore markup +# until next :startdoc: directive or end-of-file. +# - [:startdoc:] +# Specifies that \RDoc should resume parsing markup. +# - [:enddoc:] +# Specifies that \RDoc should ignore markup to end-of-file +# regardless of other directives. +# +# For Ruby code, but not for other \RDoc sources, +# there is a shorthand for [:stopdoc:] and [:startdoc:]: +# +# # Documented. +# #-- +# # Not documented. +# #++ +# # Documented. +# +# ==== Directive for Specifying \RDoc Source Format +# +# This directive described must appear on a line by itself. +# +# - [:markup: _type_] +# Specifies the format for the \RDoc input. +# Parameter +type+ is one of +markdown+, +rd+, +rdoc+, +tomdoc+. +# +# ==== Directives for HTML Output +# +# Each directive described in this section must appear on a line by itself. +# +# - [:title: _text_] +# Specifies the title for the HTML output. +# - [:main: _file_name_] +# Specifies the HTML file to be displayed first. +# +# ==== Directives for Method Documentation +# +# - [:call-seq:] +# For the given method, specifies the calling sequence to be reported in the HTML, +# overriding the actual calling sequence in the Ruby code. +# See method #call_seq_directive. +# - [:args: _arg_names_ (aliased as :arg)] +# For the given method, specifies the arguments to be reported in the HTML, +# overriding the actual arguments in the Ruby code. +# See method #args_directive. +# - [:yields: _arg_names_ (aliased as :yield:)] +# For the given method, specifies the yield arguments to be reported in the HTML, +# overriding the actual yield in the Ruby code. +# See method #yields_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. +# +# ==== 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_] +# +# Directive :section: section_title specifies that +# following methods are to be grouped into a section +# with the given section_title as its heading. +# This directive remains in effect until another such directive is given, +# but may be temporarily overridden by directive :category:. +# See below. +# +# Directive :section: with no title reverts to the default section. +# +# 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_] +# +# Directive :category: section_title specifies that +# just one following method is to be included in the given section. +# Subsequent methods are to be grouped into the current section. +# +# Directive :category: with no title specifies that just one +# following method is to be included in the default section. +# +# ==== Directive for Including a File +# +# - [:include: _filename_] +# +# Include the contents of the named file at this point. +# This directive must appear alone on one line, possibly preceded by spaces. +# In this position, it can be escaped with a backslash in front of the first colon. +# +# The file is searched for in the directories +# given with the --include command-line option, +# or in the current directory by default. +# The file content is shifted to have the same indentation as the colon +# at the start of the directive. +# +# == Markup in Code +# +# === Directives in Trailing Comments +# +# Each \RDoc directive in this section appears in a trailing +# comment in a line of code. +# +# - [:nodoc:] +# - Appears in a trailing comment on 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] +# - Appears in a trailing comment on 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:] +# - Appears in a trailing comment on 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:)] +# - Appears in a trailing comment on 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 documentaton. +# Note that instance method +initialize+ is private, and so by default +# is not documented. +# +# == 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 \ No newline at end of file diff --git a/lib/rdoc/rdoc.gemspec b/lib/rdoc/rdoc.gemspec index 547a67b04b..3c96f7deb1 100644 --- a/lib/rdoc/rdoc.gemspec +++ b/lib/rdoc/rdoc.gemspec @@ -38,16 +38,12 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat "CVE-2013-0256.rdoc", "ExampleMarkdown.md", "ExampleRDoc.rdoc", - "Gemfile", "History.rdoc", "LEGAL.rdoc", "LICENSE.rdoc", "README.rdoc", "RI.rdoc", - "Rakefile", "TODO.rdoc", - "bin/console", - "bin/setup", "exe/rdoc", "exe/ri", "lib/rdoc.rb", @@ -223,7 +219,6 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat "lib/rdoc/top_level.rb", "lib/rdoc/version.rb", "man/ri.1", - "rdoc.gemspec", ] # files from .gitignore s.files << "lib/rdoc/rd/block_parser.rb" << "lib/rdoc/rd/inline_parser.rb" << "lib/rdoc/markdown.rb" << "lib/rdoc/markdown/literals.rb"