[DOC] Add remark about in-brief for method doc

This commit is contained in:
BurdetteLamar 2024-08-07 23:21:11 +01:00 committed by Peter Zhu
parent b9a9564c1f
commit e008f0553d
Notes: git 2024-08-08 20:09:08 +00:00

View File

@ -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