Move section Directives into section Blocks (#901)

doc/rdoc/markup_reference.rb

@@ -323,6 +323,168 @@
 #
 # ---
 #
+# ==== Directives
+#
+# ===== Directives for Allowing or Suppressing Documentation
+#
+# Each directive described in this section must appear on a line by itself.
+#
+# - [<tt>:stopdoc:</tt>]
+# Specifies that \RDoc should ignore markup
+# until next <tt>:startdoc:</tt> directive or end-of-file.
+# - [<tt>:startdoc:</tt>]
+#   Specifies that \RDoc should resume parsing markup.
+# - [<tt>:enddoc:</tt>]
+#   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 [<tt>:stopdoc:</tt>] and [<tt>:startdoc:</tt>]:
+#
+#   # Documented.
+#   #--
+#   # Not documented.
+#   #++
+#   # Documented.
+#
+# ===== Directive for Specifying \RDoc Source Format
+#
+# This directive described must appear on a line by itself.
+#
+# - [<tt>:markup: _type_</tt>]
+#   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.
+#
+# - [<tt>:title: _text_</tt>]
+#   Specifies the title for the HTML output.
+# - [<tt>:main: _file_name_</tt>]
+#   Specifies the HTML file to be displayed first.
+#
+# ===== Directives for Method Documentation
+#
+# - [<tt>:call-seq:</tt>]
+#   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.
+# - [<tt>:args: _arg_names_</tt> (aliased as <tt>:arg</tt>)]
+#   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.
+# - [<tt>:yields: _arg_names_</tt> (aliased as <tt>:yield:</tt>)]
+#   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 <tt>:call-seq:</tt>
+# 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.
+#
+# - [<tt>:section: _section_title_</tt>]
+#
+#   Directive <tt>:section: <em>section_title</em></tt> specifies that
+#   following methods are to be grouped into a section
+#   with the given <em>section_title</em> as its heading.
+#   This directive remains in effect until another such directive is given,
+#   but may be temporarily overridden by directive <tt>:category:</tt>.
+#   See below.
+#
+#   Directive <tt>:section:</tt> 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 <tt>:category:</tt> to temporarily
+#   override the current section.
+#
+# - [<tt>:category: _section_title_</tt>]
+#
+#   Directive <tt>:category: <em>section_title</em></tt> 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 <tt>:category:</tt> with no title specifies that just one
+#   following method is to be included in the default section.
+#
+# ===== Directive for Including a File
+#
+# - [<tt>:include: _filename_</tt>]
+#
+#   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 <tt>--include</tt> 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.
+#
+# ===== Directives in Trailing Comments
+#
+# Each \RDoc directive in this section appears in a trailing
+# comment in a line of code.
+#
+# - [<tt>:nodoc:</tt>]
+#   - 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.
+# - [<tt>:nodoc: all</tt>]
+#   - 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
+# - [<tt>:doc:</tt>]
+#   - 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.
+# - [<tt>:notnew:</tt> (aliased as <tt>:not_new</tt> and <tt>:not-new:</tt>)]
+#   - 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.
+#
 # === Text Markup
 #
 # Text in a paragraph, list item (any type), or heading
@@ -624,170 +786,6 @@
 #
 #     {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.
-#
-# - [<tt>:stopdoc:</tt>]
-# Specifies that \RDoc should ignore markup
-# until next <tt>:startdoc:</tt> directive or end-of-file.
-# - [<tt>:startdoc:</tt>]
-#   Specifies that \RDoc should resume parsing markup.
-# - [<tt>:enddoc:</tt>]
-#   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 [<tt>:stopdoc:</tt>] and [<tt>:startdoc:</tt>]:
-#
-#   # Documented.
-#   #--
-#   # Not documented.
-#   #++
-#   # Documented.
-#
-# ==== Directive for Specifying \RDoc Source Format
-#
-# This directive described must appear on a line by itself.
-#
-# - [<tt>:markup: _type_</tt>]
-#   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.
-#
-# - [<tt>:title: _text_</tt>]
-#   Specifies the title for the HTML output.
-# - [<tt>:main: _file_name_</tt>]
-#   Specifies the HTML file to be displayed first.
-#
-# ==== Directives for Method Documentation
-#
-# - [<tt>:call-seq:</tt>]
-#   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.
-# - [<tt>:args: _arg_names_</tt> (aliased as <tt>:arg</tt>)]
-#   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.
-# - [<tt>:yields: _arg_names_</tt> (aliased as <tt>:yield:</tt>)]
-#   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 <tt>:call-seq:</tt>
-# 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.
-#
-# - [<tt>:section: _section_title_</tt>]
-#
-#   Directive <tt>:section: <em>section_title</em></tt> specifies that
-#   following methods are to be grouped into a section
-#   with the given <em>section_title</em> as its heading.
-#   This directive remains in effect until another such directive is given,
-#   but may be temporarily overridden by directive <tt>:category:</tt>.
-#   See below.
-#
-#   Directive <tt>:section:</tt> 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 <tt>:category:</tt> to temporarily
-#   override the current section.
-#
-# - [<tt>:category: _section_title_</tt>]
-#
-#   Directive <tt>:category: <em>section_title</em></tt> 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 <tt>:category:</tt> with no title specifies that just one
-#   following method is to be included in the default section.
-#
-# ==== Directive for Including a File
-#
-# - [<tt>:include: _filename_</tt>]
-#
-#   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 <tt>--include</tt> 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.
-#
-# - [<tt>:nodoc:</tt>]
-#   - 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.
-# - [<tt>:nodoc: all</tt>]
-#   - 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
-# - [<tt>:doc:</tt>]
-#   - 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.
-# - [<tt>:notnew:</tt> (aliased as <tt>:not_new</tt> and <tt>:not-new:</tt>)]
-#   - 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]