From 095b78123bea092079bbb2fae691d3888000b16a Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 2 Jan 2024 08:00:27 -0600 Subject: [PATCH] [DOC] MarkupReference (#1075) --- .document | 1 + doc/rdoc/markup_reference.rb | 89 +++++++++++++++++------------------- 2 files changed, 42 insertions(+), 48 deletions(-) diff --git a/.document b/.document index ad81ce07da..6f9390978b 100644 --- a/.document +++ b/.document @@ -3,3 +3,4 @@ LICENSE.txt README.txt RI.txt lib +doc diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index a1bbe13e2d..9e51cc4f0c 100644 --- a/doc/rdoc/markup_reference.rb +++ b/doc/rdoc/markup_reference.rb @@ -7,72 +7,61 @@ # attributes, and constants -- are solely for illustrating \RDoc markup, # and have no other legitimate use. # -# = \RDoc Markup Reference -# -# Notes: +# == About the Examples # # - Examples in this reference are Ruby code and comments; # certain differences from other sources # (such as C code and comments) are noted. +# - Almost all examples on this page are all RDoc-like; +# that is, they have no explicit comment markers like Ruby # +# or C /* ... */. # - 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: +# == \RDoc Sources # -# - .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. +# The sources of \RDoc documentation vary according to the type of file: # -# In either a Ruby or a C file, -# \RDoc ignores comments that do not precede object definitions. +# - .rb (Ruby code file): # -# 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. +# - Markup may be found in Ruby comments: +# A comment that immediately precedes the definition +# of a Ruby class, module, method, alias, constant, or attribute +# becomes the documentation for that defined object. +# - An \RDoc directive may be found in: # -# Almost all examples on this page are all RDoc-like; -# that is, they have no comment markers like Ruby # -# or C /* ... */. +# - A trailing comment (on the same line as code); +# see :nodoc:, :doc:, and :notnew:. +# - A single-line comment; +# see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives]. # -# === Margins +# - Documentation may be derived from the Ruby code itself; +# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code]. # -# 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. +# - .c (C code file): markup is parsed from C comments. +# A comment that immediately precedes +# a function that implements a Ruby method, +# or otherwise immediately precedes the definition of a Ruby object, +# becomes the documentation for that object. +# - .rdoc (\RDoc markup text file) or .md (\RDoc markdown text file): +# markup is parsed from the entire file. +# The text is not associated with any code object, +# but may (depending on how the documentation is built) +# become a separate page. +# +# An RDoc document: +# +# - A (possibly multi-line) comment in a Ruby or C file +# that generates \RDoc documentation (as above). +# - The entire markup (.rdoc) file or markdown (.md) file +# (which is usually multi-line). # # === Blocks # -# It's convenient to think of \RDoc markup input as a sequence of _blocks_ +# It's convenient to think of an \RDoc document as a sequence of _blocks_ # of various types (details at the links): # # - {Paragraph}[rdoc-ref:RDoc::MarkupReference@Paragraphs]: @@ -88,7 +77,7 @@ # - {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. +# a heading. # - {Horizontal rule}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules]: # a line across the rendered page. # - {Directive}[rdoc-ref:RDoc::MarkupReference@Directives]: @@ -103,6 +92,10 @@ # - Any block may appear independently # (that is, not nested in another block); # some blocks may be nested, as detailed below. +# - In a multi-line block, +# \RDoc looks for the block's natural left margin, +# which becomes the base margin for the block +# and is the initial current margin for the block. # # ==== Paragraphs #