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