mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
[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.
This commit is contained in:
parent
86bd9146a7
commit
1dd2d2ce48
Notes:
git
2022-03-07 20:04:47 +09:00
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
1 changed files with 11 additions and 10 deletions
|
@ -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.
|
||||
|
||||
|
|
Loading…
Add table
Reference in a new issue