https://git.ruby-lang.org/ruby.git/commit/?id=e3a988a29c

From e3a988a29c2cfa4a7e2e045d82989a7342955be8 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Y...>
Date: Tue, 12 Jul 2022 20:49:24 -0500
Subject: [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`: https://github.com/ruby/ruby/blob/trunk/doc/contributing/documentation_guide.md#L92
 
     Example:
 
-    ```c
+    ```
     /*
      *  call-seq:
      *    each_byte {|byte| ... } -> self
@@ -215,59 +215,85 @@ For methods written in Ruby, \RDoc documents the calling sequence automatically. https://github.com/ruby/ruby/blob/trunk/doc/contributing/documentation_guide.md#L215
 
 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`. https://github.com/ruby/ruby/blob/trunk/doc/contributing/documentation_guide.md#L367
 
 Mention aliases in the form
 
-```c
+```
 // Array#find_index is an alias for Array#index.
 ```
 
-- 
cgit v1.2.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/