Skip to content

Commit

Permalink
Move section Directives into section Blocks (#901)
Browse files Browse the repository at this point in the history
  • Loading branch information
@BurdetteLamar
BurdetteLamar authored Jul 25, 2022
1 parent db5f76f commit e48e07e
Showing 1 changed file with 162 additions and 164 deletions.
326 changes: 162 additions & 164 deletions doc/rdoc/markup_reference.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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]
Expand Down

0 comments on commit e48e07e

Please sign in to comment.