diff options
| author | BurdetteLamar <[email protected]> | 2024-08-07 23:21:11 +0100 |
|---|---|---|
| committer | Peter Zhu <[email protected]> | 2024-08-08 16:08:47 -0400 |
| commit | e008f0553dd1e1dcfe43a50af93169e1e2e11c04 (patch) | |
| tree | 48aa2f4108734414db0d0f4884c496155aa44a64 | |
| parent | b9a9564c1f1359d4d4022d099d57bcb9789b692c (diff) | |
[DOC] Add remark about in-brief for method doc
Notes
Notes:
Merged: https://github.com/ruby/ruby/pull/11330
| -rw-r--r-- | doc/contributing/documentation_guide.md | 11 |
1 files changed, 11 insertions, 0 deletions
diff --git a/doc/contributing/documentation_guide.md b/doc/contributing/documentation_guide.md index b27c453ff3..0c7f6892d2 100644 --- a/doc/contributing/documentation_guide.md +++ b/doc/contributing/documentation_guide.md @@ -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 |