From e3a988a29c2cfa4a7e2e045d82989a7342955be8 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Tue, 12 Jul 2022 20:49:24 -0500
Subject: [PATCH] [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.
---
 doc/contributing/documentation_guide.md | 94 ++++++++++++++++---------
 1 file 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).
+
+For a singleton method, use the form:
+
+```
+class_name.method_name(method_args) {|block_args| ... } -> return_type
+```
 
 Example:
 
-```c
+```
 *  call-seq:
-*    array.count -> integer
-*    array.count(obj) -> integer
-*    array.count {|element| ... } -> integer
+*    Hash.new(default_value = nil) -> new_hash
+*    Hash.new {|hash, key| ... } -> new_hash
 ```
 
-When creating the `call-seq`, use the form
+For an instance method, use the form
+(omitting any prefix, just as RDoc does for a Ruby-coded method):
 
 ```
-receiver_type.method_name(arguments) {|block_arguments|} -> return_type
+method_name(method_args) {|block_args| ... } -> return_type
 ```
-
-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 example, in Array, use:
 
 ```
-obj.respond_to?(symbol, include_all=false) -> true or false
+*  call-seq:
+*    count -> integer
+*    count(obj) -> integer
+*    count {|element| ... } -> integer
 ```
 
-Instead of:
-
 ```
-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:
 
-Omit aliases from the `call-seq`, but mention them near the end (see below).
+- 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:
 
-A `call-seq` block should have `{|x| ... }`, not `{|x| block }` or `{|x| code }`.
+        ```
+        respond_to?(symbol, include_all = false) -> true or false
+        ```
 
-A `call-seq` output should:
+    - If the behavior is different with an omitted or an explicit argument,
+      use a `call-seq` with separate lines.
+      For example, in Enumerable, use:
 
-- 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`.
+        ```
+        *    max    -> element
+        *    max(n) -> array
+        ```
+
+Block:
+
+- 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 }`.
+
+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.
 ```