diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index 97293d5cba..0e0de430a6 100644 --- a/doc/rdoc/markup_reference.rb +++ b/doc/rdoc/markup_reference.rb @@ -439,76 +439,75 @@ # # ===== Directives for Allowing or Suppressing Documentation # -# - # :stopdoc:: +# ====== :stopdoc: # -# - Appears on a line by itself. -# - Specifies that \RDoc should ignore markup -# until next :startdoc: directive or end-of-file. +# - Appears on a line by itself. +# - Specifies that \RDoc should ignore markup +# until next :startdoc: directive or end-of-file. # -# - # :startdoc:: +# ====== :startdoc: # -# - Appears on a line by itself. -# - Specifies that \RDoc should resume parsing markup. +# - Appears on a line by itself. +# - Specifies that \RDoc should resume parsing markup. # -# - # :enddoc:: +# ====== :enddoc: # -# - Appears on a line by itself. -# - 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 to end-of-file +# regardless of other directives. # -# - # :nodoc:: +# ====== :nodoc: # -# - Appended to a line of code -# that defines a class, module, method, alias, constant, or attribute. +# - Appended to a line of code +# that defines a class, module, method, alias, constant, or attribute; +# takes optional argument +all+ (:nodoc: all). +# - Specifies that the defined object should not be documented. # -# - Specifies that the defined object should not be documented. +# For a method definition in C code, it the directive must be in the comment line +# immediately preceding the definition: # -# - For a method definition in C code, it the directive must be in the comment line -# immediately preceding the definition: +# /* :nodoc: */ +# static VALUE +# some_method(VALUE self) +# { +# return self; +# } # -# /* :nodoc: */ -# static VALUE -# some_method(VALUE self) -# { -# return self; -# } +# Note that this directive has no effect at all +# when placed at the method declaration: # -# Note that this directive has no effect at all -# when placed at the method declaration: +# /* :nodoc: */ +# rb_define_method(cMyClass, "do_something", something_func, 0); # -# /* :nodoc: */ -# rb_define_method(cMyClass, "do_something", something_func, 0); +# The above comment is just a comment and has nothing to do with \RDoc. +# Therefore, +do_something+ method will be reported as "undocumented" +# unless that method or function is documented elsewhere. # -# The above comment is just a comment and has nothing to do with \RDoc. -# Therefore, +do_something+ method will be reported as "undocumented" -# unless that method or function is documented elsewhere. +# For a constant definition in C code, this directive can not work +# because there is no "implementation" place for a constant. # -# - For a constant definition in C code, this directive can not work -# because there is no "implementation" place for a constant. +# With argument +all+ (:nodoc: all), +# specifies that the class or module should not be documented. +# By default, however, a nested class or module _will_ be documented. # -# - # :nodoc: all: +# ====== :doc: # -# - 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. +# - 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 it otherwise +# would not be documented. # -# - # :doc:: +# ====== :notnew: # -# - 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 it otherwise -# would not be documented. +# - 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. # -# - # :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. +# Aliased as :not_new: and :not-new:. # # For Ruby code, but not for other \RDoc sources, # there is a shorthand for :stopdoc: and :startdoc:: @@ -528,45 +527,49 @@ # # ===== Directive for Specifying \RDoc Source Format # -# - # :markup: _type_: +# ====== :markup: # -# - Appears on a line by itself. -# - Specifies the format for the \RDoc input; -# parameter +type+ is one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+. -# See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats]. +# - Appears on a line by itself; takes argument +format+ (:markup: _format_). +# - Specifies the format for the \RDoc input; +# argument +format+ is one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+. +# See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats]. # # ===== Directives for Method Documentation # -# - # :call-seq:: +# ====== :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: # -# - 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. +# - A return type, which is not automatically inferred. +# - Multiple calling sequences. # -# 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: +# For C code, the directive may appear in a stand-alone comment. # -# - A return type, which is not automatically inferred. -# - Multiple calling sequences. +# ====== :args: # -# For C code, the directive may appear in a stand-alone comment. +# - Appears on a line by itself; takes argument +arg_names+ (:args: _arg_names_). +# - Specifies the arguments to be reported in the HTML, +# overriding the actual arguments in the code. +# See method #args_directive. # -# - # :args: _arg_names_ (aliased as :arg:): +# 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: # -# - # :yields: _arg_names_ (aliased as :yield:): +# - Appears on a line by itself; takes argument +arg_names+ (:yields: _arg_names_). +# - Specifies the yield arguments to be reported in the HTML, +# overriding the actual yield in the code. +# See method #yields_directive. # -# - 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. +# Aliased as :yield:. # # ===== Directives for Organizing Documentation # @@ -578,64 +581,65 @@ # # You can use directives to modify those behaviors. # -# - # :section: _section_title_: -# -# - 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: -# -# - 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 +# ====== :section: +# +# - Appears on a line by itself; takes argument +section_title+ (:section: _section_title_). +# - 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: # -# You can use directive :category: to temporarily -# override the current section. +# - 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. # -# - # :category: _section_title_: +# Example: # -# - 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. +# # ---------------------------------------- +# # :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: +# +# - Appears on a line by itself; takes argument +section_title+ (:category: _section_title_). +# - 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: _filepath_: +# ====== :include: +# +# - Appears on a line by itself; takes argument +filepath+ (:include: _filepath_). +# - Specifies that the contents of the given file +# are to be included at this point. # -# - 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. +# The file content is shifted to have the same indentation as the colon +# at the start of the directive. # -# The file is searched for in the directory containing the current file, -# and then in each of the directories given with the --include -# command-line option. +# The file is searched for in the directory containing the current file, +# and then in each of the directories given with the --include +# command-line option. # -# For C code, the directive may appear in a stand-alone comment +# For C code, the directive may appear in a stand-alone comment # # ==== Text Markup #