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:
parent
de51bbcb54
commit
e3a988a29c
Notes:
git
2022-07-13 10:49:47 +09:00
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
1 changed files with 60 additions and 34 deletions
|
@ -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.
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue