diff options
| author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2022-03-07 05:04:16 -0600 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-03-07 05:04:16 -0600 |
| commit | 1dd2d2ce48d7ed0e16beb42ac923ccd069701958 (patch) | |
| tree | 0475f3ea493703e8844ebf3c34b83af639f76284 | |
| parent | 86bd9146a78f5461e2d41136741016f27de46dd7 (diff) | |
[DOC] Change to guidance on lists in What's Here section (#5618)
Currently, the guide says a "What's Here" section should have a labeled list for the methods. Such a list can render very differently in different browsers, and are often erratic in their indentation of continuation lines.
| -rw-r--r-- | doc/documentation_guide.rdoc | 21 |
1 files changed, 11 insertions, 10 deletions
diff --git a/doc/documentation_guide.rdoc b/doc/documentation_guide.rdoc index 38438e94b4..ff1bb88565 100644 --- a/doc/documentation_guide.rdoc +++ b/doc/documentation_guide.rdoc @@ -111,16 +111,17 @@ Guidelines: - Consider listing the parent class and any included modules; consider {links}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Links] to their "What's Here" sections if those exist. -- List methods as a {labeled list}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Labeled+Lists]. -- Each list entry's label is a method name; - if the method has aliases, include those with the "base" method method, - and do not list them separately. -- Check the rendered documentation to determine whether \RDoc has recognized - the method and linked to it; if not, manually insert a - {link}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Links]. -- Each entry's description is a 1-line synopsis for the method. -- Keep the description short. -- If there are more entries, consider gouping them into subsections with headers. +- List methods as a bullet list: + + - Begin each item with the method name, followed by a colon + and a short description. + - If the method has aliases, mention them in parentheses before the colon + (and do not list the aliases separately). + - Check the rendered documentation to determine whether \RDoc has recognized + the method and linked to it; if not, manually insert a + {link}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-Links]. + +- If there are numerous entries, consider grouping them into subsections with headers. - If there are more than a few such subsections, consider adding a table of contents just below the main section title. |