[DOC] Add remark about in-brief for method doc
This commit is contained in:
parent
b9a9564c1f
commit
e008f0553d
Notes:
git
2024-08-08 20:09:08 +00:00
@ -382,6 +382,7 @@ The general structure of the method documentation should be:
|
||||
|
||||
- Calling sequence (for methods written in C).
|
||||
- Synopsis (short description).
|
||||
- In-brief examples (optional)
|
||||
- Details and examples.
|
||||
- Argument description (if necessary).
|
||||
- Corner cases and exceptions.
|
||||
@ -502,6 +503,16 @@ This is great as it is short and descriptive. Avoid documenting
|
||||
too much in the synopsis, stick to the most important information
|
||||
for the benefit of the reader.
|
||||
|
||||
### In-Brief Examples
|
||||
|
||||
For a method whose documentation is lengthy,
|
||||
consider adding an "in-brief" passage,
|
||||
showing examples that summarize the method's uses.
|
||||
|
||||
The passage may answer some users' questions
|
||||
(without their having to read long documentation);
|
||||
see Array#[] and Array#[]=.
|
||||
|
||||
### Details and Examples
|
||||
|
||||
Most non-trivial methods benefit from examples, as well as details
|
||||
|
Loading…
x
Reference in New Issue
Block a user