1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
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 
Merged: https://github.com/ruby/ruby/pull/11330
1 changed files with 11 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
doc/contributing/documentation_guide.md
View File

@ -382,6 +382,7 @@ The general structure of the method documentation should be:
- Calling sequence (for methods written in C). - Calling sequence (for methods written in C).
- Synopsis (short description). - Synopsis (short description).
- In-brief examples (optional)
- Details and examples. - Details and examples.
- Argument description (if necessary). - Argument description (if necessary).
- Corner cases and exceptions. - 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 too much in the synopsis, stick to the most important information
for the benefit of the reader. 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 ### Details and Examples
Most non-trivial methods benefit from examples, as well as details Most non-trivial methods benefit from examples, as well as details