Skip to content

Commit

Permalink
[DOC] Make example formats explicit and consistent (#913)
Browse files Browse the repository at this point in the history
  • Loading branch information
BurdetteLamar authored Aug 11, 2022
1 parent dc88f1b commit 7e6ef6c
Showing 1 changed file with 87 additions and 66 deletions.
153 changes: 87 additions & 66 deletions doc/rdoc/markup_reference.rb
Original file line number Diff line number Diff line change
Expand Up @@ -29,16 +29,37 @@
# 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
# becomes the documentation for that defined object.
# The treatment of markup in comments varies according to the type of file:
#
# (\RDoc ignores other such comments that do not precede definitions.)
# - <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.
#
# 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 <tt>#</tt>
# or C <tt>/* ... */</tt>.
#
# === Margins
#
Expand Down Expand Up @@ -96,11 +117,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 @@ -133,15 +154,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 @@ -279,13 +300,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 @@ -305,13 +326,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 @@ -331,13 +352,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 @@ -356,13 +377,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 @@ -381,20 +402,20 @@
#
# 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
#
# A heading may contain only one type of nested block:
#
Expand Down Expand Up @@ -1147,10 +1168,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

0 comments on commit 7e6ef6c

Please sign in to comment.