[DOC] Revisions for call-seq in doc guidelines (#6121)

    Splits certain guidelines for singleton and instance method.
    Calls for instance method to not prefix anything (like RDoc itself for a Ruby-coded instance method); e.g.:
        count -> integer, not array.count,.
        <=> other -> integer or nil, not hash <=> other -> integer or nil.
    Groups previous guidelines into Arguments, Block, Return types, Aliases.

1 files changed, 60 insertions, 34 deletions

diff --git a/doc/contributing/documentation_guide.md b/doc/contributing/documentation_guide.md
index 6219ec605c..f011841809 100644
--- a/doc/contributing/documentation_guide.md
+++ b/doc/contributing/documentation_guide.md
@@ -92,7 +92,7 @@ involving new files `doc/*.rdoc`:
 
     Example:
 
-    ```c
+    ```
     /*
      *  call-seq:
      *    each_byte {|byte| ... } -> self
@@ -215,59 +215,85 @@ For methods written in Ruby, \RDoc documents the calling sequence automatically.
 
 For methods written in C, \RDoc cannot determine what arguments
 the method accepts, so those need to be documented using \RDoc directive
-[`:call-seq:`](rdoc-ref:RDoc::Markup@Method+arguments).
+[`call-seq:`](rdoc-ref:RDoc::Markup@Method+arguments).
 
-Example:
+For a singleton method, use the form:
 
-```c
-*  call-seq:
-*    array.count -> integer
-*    array.count(obj) -> integer
-*    array.count {|element| ... } -> integer
+```
+class_name.method_name(method_args) {|block_args| ... } -> return_type
 ```
 
-When creating the `call-seq`, use the form
+Example:
 
 ```
-receiver_type.method_name(arguments) {|block_arguments|} -> return_type
+*  call-seq:
+*    Hash.new(default_value = nil) -> new_hash
+*    Hash.new {|hash, key| ... } -> new_hash
 ```
 
-Omit the parentheses for cases where the method does not accept arguments,
-and omit the block for cases where a block is not accepted.
-
-In the cases where method can return multiple different types, separate the
-types with "or".  If the method can return any type, use "object".  If the
-method returns the receiver, use "self".
-
-In cases where the method accepts optional arguments, use a `call-seq` with
-an optional argument if the method has the same behavior when an argument is
-omitted as when the argument is passed with the default value.  For example,
-use:
+For an instance method, use the form
+(omitting any prefix, just as RDoc does for a Ruby-coded method):
 
 ```
-obj.respond_to?(symbol, include_all=false) -> true or false
+method_name(method_args) {|block_args| ... } -> return_type
 ```
+For example, in Array, use:
 
-Instead of:
+```
+*  call-seq:
+*    count -> integer
+*    count(obj) -> integer
+*    count {|element| ... } -> integer
+```
 
 ```
-obj.respond_to?(symbol) -> true or false
-obj.respond_to?(symbol, include_all) -> true or false
+* call-seq:
+*    <=> other -> -1, 0, 1, or nil
 ```
 
-However, as shown above for `Array#count`, use separate lines if the
-behavior is different if the argument is omitted.
+Arguments:
+
+- If the method does not accept arguments, omit the parentheses.
+- If the method accepts optional arguments:
+
+    - Separate each argument name and its default value with ` = `
+      (equal-sign with surrounding spaces).
+    - If the method has the same behavior with either an omitted
+      or an explicit argument, use a `call-seq` with optional arguments.
+      For example, use:
+
+        ```
+        respond_to?(symbol, include_all = false) -> true or false
+        ```
 
-Omit aliases from the `call-seq`, but mention them near the end (see below).
+    - If the behavior is different with an omitted or an explicit argument,
+      use a `call-seq` with separate lines.
+      For example, in Enumerable, use:
 
+        ```
+        *    max    -> element
+        *    max(n) -> array
+        ```
 
-A `call-seq` block should have `{|x| ... }`, not `{|x| block }` or `{|x| code }`.
+Block:
 
-A `call-seq` output should:
+- If the method does not accept a block, omit the block.
+- If the method accepts a block, the `call-seq` should have `{|args| ... }`,
+  not `{|args| block }` or `{|args| code }`.
 
-- Have `self`, not `receiver` or `array`.
-- Begin with `new_` if and only if the output object is a new instance
-  of the receiver's class, to emphasize that the output object is not `self`.
+Return types:
+
+- If the method can return multiple different types,
+  separate the types with "or" and, if necessary, commas.
+- If the method can return multiple types, use +object+.
+- If the method returns the receiver, use +self+.
+- If the method returns an object of the same class,
+  prefix `new_` if an only if the object is not  +self+;
+  example: `new_array`.
+
+Aliases:
+
+- Omit aliases from the `call-seq`, but mention them near the end (see below).
 
 ### Synopsis
 
@@ -341,7 +367,7 @@ that is a common case, such as `Hash#fetch` raising a `KeyError`.
 
 Mention aliases in the form
 
-```c
+```
 // Array#find_index is an alias for Array#index.
 ```