diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index 77e34cfb37..cc10b04871 100644 --- a/doc/rdoc/markup_reference.rb +++ b/doc/rdoc/markup_reference.rb @@ -327,19 +327,55 @@ # # ===== Directives for Allowing or Suppressing Documentation # -# Each directive described in this section must appear on a line by itself. +# - # :stopdoc:: # -# - [: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. +# - Appears on a line by itself. +# - Specifies that \RDoc should ignore markup +# until next :startdoc: directive or end-of-file. +# +# - # :startdoc:: +# +# - Appears on a line by itself. +# - Specifies that \RDoc should resume parsing markup. +# +# - # :enddoc:: +# +# - Appears on a line by itself. +# - Specifies that \RDoc should ignore markup to end-of-file +# regardless of other directives. +# +# - # :nodoc:: +# +# - Appended to 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: +# +# - Appended to 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:: +# +# - Appended to 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:): +# +# - Appended to 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 documentation. +# Note that instance method +initialize+ is private, and so by default +# is not documented. # # For Ruby code, but not for other \RDoc sources, -# there is a shorthand for [:stopdoc:] and [:startdoc:]: +# there is a shorthand for :stopdoc: and :startdoc:: # # # Documented. # #-- @@ -347,45 +383,64 @@ # #++ # # Documented. # +# For C code, any of directives :startdoc:, :enddoc:, +# and :nodoc: may appear in a stand-alone comment: +# +# /* :startdoc: */ +# /* :stopdoc: */ +# /* :enddoc: */ +# # ===== Directive for Specifying \RDoc Source Format # -# This directive described must appear on a line by itself. +# - # :markup: _type_: # -# - [:markup: _type_] -# Specifies the format for the \RDoc input. -# Parameter +type+ is one of +markdown+, +rd+, +rdoc+, +tomdoc+. +# - Appears on a line by itself. +# - 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_: # -# - [:title: _text_] -# Specifies the title for the HTML output. -# - [:main: _file_name_] -# Specifies the HTML file to be displayed first. +# - Appears on a line by itself. +# - Specifies the title for the HTML output. +# +# - # :main: _filename_: +# - Appears on a line by itself. +# - 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. +# - # :call-seq:: +# +# - Appears on a line by itself. +# - Specifies the calling sequence to be reported in the HTML, +# overriding the actual calling sequence in the code. +# See method #call_seq_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. +# +# For C code, the directive may appear in a stand-alone comment. +# +# - # :args: _arg_names_ (aliased as :arg:): +# +# - Appears on a line by itself. +# - Specifies the arguments to be reported in the HTML, +# overriding the actual arguments in the code. +# See method #args_directive. +# +# - # :yields: _arg_names_ (aliased as :yield:): +# +# - Appears on a line by itself. +# - Specifies the yield arguments to be reported in the HTML, +# overriding the actual yield in the code. +# See method #yields_directive. # # ===== Directives for Organizing Documentation # @@ -397,16 +452,15 @@ # # 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. +# - # :section: _section_title_: # -# Directive :section: with no title reverts to the default section. +# - Appears on a line by itself. +# - Specifies that following methods are to be grouped into the section +# with the given section_title, +# or into the default section if no title is given. +# The directive remains in effect until another such directive is given, +# but may be temporarily overridden by directive :category:. +# See below. # # The comment block containing this directive: # @@ -434,56 +488,28 @@ # You can use directive :category: to temporarily # override the current section. # -# - [:category: _section_title_] +# - # :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. +# - Appears on a line by itself. +# - Specifies that just one following method is to be included +# in the given section, or in the default section if no title is given. +# Subsequent methods are to be grouped into the current 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. +# - # :include: _filepath_: # -# ===== Directives in Trailing Comments +# - Appears on a line by itself. +# - Specifies that the contents of the given file +# are to be included at this point. +# The file content is shifted to have the same indentation as the colon +# at the start of the directive. # -# Each \RDoc directive in this section appears in a trailing -# comment in a line of code. +# The file is searched for in the directories +# given with the --include command-line option, +# or by default in the current directory. # -# - [: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. +# For C code, the directive may appear in a stand-alone comment # # === Text Markup #