1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00

[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.
This commit is contained in:
Burdette Lamar 2022-07-12 20:49:24 -05:00 committed by GitHub
parent de51bbcb54
commit e3a988a29c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
Notes: git 2022-07-13 10:49:47 +09:00
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>

View file

@ -92,7 +92,7 @@ involving new files `doc/*.rdoc`:
Example: Example:
```c ```
/* /*
* call-seq: * call-seq:
* each_byte {|byte| ... } -> self * 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 For methods written in C, \RDoc cannot determine what arguments
the method accepts, so those need to be documented using \RDoc directive 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: Example:
```c ```
* call-seq: * call-seq:
* array.count -> integer * Hash.new(default_value = nil) -> new_hash
* array.count(obj) -> integer * Hash.new {|hash, key| ... } -> new_hash
* array.count {|element| ... } -> integer
``` ```
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
``` ```
For example, in Array, use:
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:
``` ```
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 * call-seq:
obj.respond_to?(symbol, include_all) -> true or false * <=> other -> -1, 0, 1, or nil
``` ```
However, as shown above for `Array#count`, use separate lines if the Arguments:
behavior is different if the argument is omitted.
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 * max -> element
of the receiver's class, to emphasize that the output object is not `self`. * 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 ### Synopsis
@ -341,7 +367,7 @@ that is a common case, such as `Hash#fetch` raising a `KeyError`.
Mention aliases in the form Mention aliases in the form
```c ```
// Array#find_index is an alias for Array#index. // Array#find_index is an alias for Array#index.
``` ```