Skip to content

[DOC] Make example formats explicit and consistent #913

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BurdetteLamar merged 6 commits into from
Aug 11, 2022
Merged

[DOC] Make example formats explicit and consistent #913

Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cf78fb3
Make example formats explicit and consistent
BurdetteLamar Aug 8, 2022
db874d1
Make example formats explicit and consistent
BurdetteLamar Aug 9, 2022
bfaf8ed
Make example formats explicit and consistent
BurdetteLamar Aug 9, 2022
62ba613
Make example formats explicit and consistent
BurdetteLamar Aug 10, 2022
4ebe159
Make example formats explicit and consistent
BurdetteLamar Aug 10, 2022
da2f918
Merge branch 'master' into example_formats
BurdetteLamar Aug 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
231 changes: 122 additions & 109 deletions doc/rdoc/markup_reference.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,16 +29,29 @@
# see <tt>:nodoc:</tt>, <tt>:doc:</tt>, and <tt>:notnew</tt>.
# - \RDoc directives in single-line comments;
# see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives].
# - The Ruby code itself;
# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code]
# - 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
#
# A single-line or multi-line comment that immediately precedes
# the definition of a class, module, method, alias, constant, or attribute
# The treatment of markup in comments varies according to the type of file:
#
# - <tt>.rb</tt> (Ruby code file): markup is parsed from Ruby comments.
# - <tt>.c</tt> (C code file): markup is parsed from C comments.
# - <tt>.rdoc</tt> (RDoc text file): markup is parsed from the entire file.
#
# In Ruby or C file, a comment that immediately precedes the definition
# of a Ruby class, module, method, alias, constant, or attribute
# becomes the documentation for that defined object.
# \RDoc ignores other such comments that do not precede object definitions.
#
# (\RDoc ignores other such comments that do not precede 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 <tt>#</tt>
# or C <tt>/* ... */</tt>.
#
# === Margins
#
Expand Down Expand Up @@ -82,11 +95,11 @@
#
# 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.
# \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:
# >>>
Expand Down Expand Up @@ -118,15 +131,15 @@
#
# 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.
# 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:
# >>>
Expand Down Expand Up @@ -253,13 +266,13 @@
#
# Example input:
#
# # - An item.
# # - Another.
# # - An item spanning
# # multiple lines.
# #
# # * Yet another.
# # - Last one.
# - An item.
# - Another.
# - An item spanning
# multiple lines.
#
# * Yet another.
# - Last one.
#
# Rendered HTML:
# >>>
Expand All @@ -279,13 +292,13 @@
#
# Example input:
#
# # 100. An item.
# # 10. Another.
# # 1. An item spanning
# # multiple lines.
# #
# # 1. Yet another.
# # 1000. Last one.
# 100. An item.
# 10. Another.
# 1. An item spanning
# multiple lines.
#
# 1. Yet another.
# 1000. Last one.
#
# Rendered HTML:
# >>>
Expand All @@ -305,13 +318,13 @@
#
# Example input:
#
# # z. An item.
# # y. Another.
# # x. An item spanning
# # multiple lines.
# #
# # x. Yet another.
# # a. Last one.
# z. An item.
# y. Another.
# x. An item spanning
# multiple lines.
#
# x. Yet another.
# a. Last one.
#
# Rendered HTML:
# >>>
Expand All @@ -330,13 +343,13 @@
#
# Example input:
#
# # [foo] An item.
# # bat:: Another.
# # [bag] An item spanning
# # multiple lines.
# #
# # [bar baz] Yet another.
# # bam:: Last one.
# [foo] An item.
# bat:: Another.
# [bag] An item spanning
# multiple lines.
#
# [bar baz] Yet another.
# bam:: Last one.
#
# Rendered HTML:
# >>>
Expand All @@ -355,35 +368,35 @@
#
# 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
# = 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.
# #
# # ---
# ------
# Stuff between.
#
# \--- Not a horizontal rule.
#
# -- Also not a horizontal rule.
#
# ---
#
# Rendered HTML:
# >>>
Expand Down Expand Up @@ -595,47 +608,47 @@
#
# 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
# _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:
#
# # <i>Two words</i> in paragraph.
# # - <i>Two words</i> in bullet list item.
# # 1. <i>Two words</i> in numbered list item.
# # a. <i>Two words</i> in lettered list item.
# # [<i>Two words</i>] <i>Two words</i> in labeled list item.
# # ====== <i>Two words</i> in heading
# <i>Two words</i> in paragraph.
# - <i>Two words</i> in bullet list item.
# 1. <i>Two words</i> in numbered list item.
# a. <i>Two words</i> in lettered list item.
# [<i>Two words</i>] <i>Two words</i> in labeled list item.
# ====== <i>Two words</i> 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
# *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:
#
# # <b>Two words</b> in paragraph.
# # - <b>Two words</b> in bullet list item.
# # 1. <b>Two words</b> in numbered list item.
# # a. <b>Two words</b> in lettered list item.
# # [<b>Two words</b>] <b>Two words</b> in labeled list item.
# # ====== <b>Two words</b> in heading
# <b>Two words</b> in paragraph.
# - <b>Two words</b> in bullet list item.
# 1. <b>Two words</b> in numbered list item.
# a. <b>Two words</b> in lettered list item.
# [<b>Two words</b>] <b>Two words</b> in labeled list item.
# ====== <b>Two words</b> in heading
#
# ==== Monofont
#
Expand All @@ -644,23 +657,23 @@
#
# 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
# +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:
#
# # <tt>Two words</tt> in paragraph.
# # - <tt>Two words</tt> in bullet list item.
# # 1. <tt>Two words</tt> in numbered list item.
# # a. <tt>Two words</tt> in lettered list item.
# # [<tt>Two words</tt>] <tt>Two words</tt> in labeled list item.
# # ====== <tt>Two words</tt> in heading
# <tt>Two words</tt> in paragraph.
# - <tt>Two words</tt> in bullet list item.
# 1. <tt>Two words</tt> in numbered list item.
# a. <tt>Two words</tt> in lettered list item.
# [<tt>Two words</tt>] <tt>Two words</tt> in labeled list item.
# ====== <tt>Two words</tt> in heading
#
# ==== Escaping Text Markup
#
Expand Down Expand Up @@ -1008,10 +1021,10 @@ def dummy_instance_method(foo, bar); end;
#
# Here is the <tt>:call-seq:</tt> directive given for the method:
#
# # :call-seq:
# # call_seq_directive(foo, bar)
# # Can be anything -> bar
# # Also anything more -> baz or bat
# :call-seq:
# call_seq_directive(foo, bar)
# Can be anything -> bar
# Also anything more -> baz or bat
#
def call_seq_directive
nil
Expand Down