[DOC] Clarifications for directives (#903)

-  Former section "Directives in Trailing Comments" is reworked. The important thing about a directive is what it does, not whether it's trailing or stand-alone. Therefore I've worked the directives in the former section into the appropriate sections, based on function.
- Each directive is now explicitly marked as trailing or stand-alone.
- C-code directives are mentioned only for those directives that actually appear in our ruby/ruby C files, which are :startdoc:, :stopdoc:, :enddoc:, :include:, and :call-seq:. What effect, if any, other directives have in C, I'm not sure about.

doc/rdoc/markup_reference.rb

@@ -327,65 +327,120 @@
 #
 # ===== Directives for Allowing or Suppressing Documentation
 #
-# Each directive described in this section must appear on a line by itself.
+# - <tt># :stopdoc:</tt>:
 #
-# - [<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.
+#   - Appears on a line by itself.
+#   - Specifies that \RDoc should ignore markup
+#     until next <tt>:startdoc:</tt> directive or end-of-file.
+#
+# - <tt># :startdoc:</tt>:
+#
+#   - Appears on a line by itself.
+#   - Specifies that \RDoc should resume parsing markup.
+#
+# - <tt># :enddoc:</tt>:
+#
+#   - Appears on a line by itself.
+#   - Specifies that \RDoc should ignore markup to end-of-file
+#     regardless of other directives.
+#
+# - <tt># :nodoc:</tt>:
+#
+#   - 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.
+#
+# - <tt># :nodoc: all</tt>:
+#
+#   - 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.
+#
+# - <tt># :doc:</tt>:
+#
+#   - 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.
+#
+# - <tt># :notnew:</tt> (aliased as <tt>:not_new:</tt> and <tt>:not-new:</tt>):
+#
+#   - 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 [<tt>:stopdoc:</tt>] and [<tt>:startdoc:</tt>]:
+# there is a shorthand for <tt>:stopdoc:</tt> and <tt>:startdoc:</tt>:
 #
 #   # Documented.
 #   #--
 #   # Not documented.
 #   #++
 #   # Documented.
 #
+# For C code, any of directives <tt>:startdoc:</tt>, <tt>:enddoc:</tt>,
+# and <tt>:nodoc:</tt> 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.
+# - <tt># :markup: _type_</tt>:
 #
-# - [<tt>:markup: _type_</tt>]
-#   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.
+# - <tt># :title: _text_</tt>:
 #
-# - [<tt>:title: _text_</tt>]
-#   Specifies the title for the HTML output.
-# - [<tt>:main: _file_name_</tt>]
-#   Specifies the HTML file to be displayed first.
+#   - Appears on a line by itself.
+#   - Specifies the title for the HTML output.
+#
+# - <tt># :main: _filename_</tt>:
+#   - Appears on a line by itself.
+#   - 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.
+# - <tt># :call-seq:</tt>:
+#
+#   - 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 <tt>:call-seq:</tt>
+#   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.
+#
+# - <tt># :args: _arg_names_</tt> (aliased as <tt>:arg:</tt>):
+#
+#   - 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.
+#
+# - <tt># :yields: _arg_names_</tt> (aliased as <tt>:yield:</tt>):
+#
+#   - 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.
 #
-# - [<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.
+# - <tt># :section: _section_title_</tt>:
 #
-#   Directive <tt>:section:</tt> 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 <em>section_title</em>,
+#     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 <tt>:category:</tt>.
+#     See below.
 #
 #   The comment block containing this directive:
 #
@@ -434,56 +488,28 @@
 #   You can use directive <tt>:category:</tt> to temporarily
 #   override the current section.
 #
-# - [<tt>:category: _section_title_</tt>]
+# - <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.
+#   - 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
 #
-# - [<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.
+# - <tt># :include: _filepath_</tt>:
 #
-# ===== 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 <tt>--include</tt> command-line option,
+#     or by default in the current directory.
 #
-# - [<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.
+#   For C code, the directive may appear in a stand-alone comment
 #
 # === Text Markup
 #