https://git.ruby-lang.org/ruby.git/commit/?id=1dd2d2ce48

From 1dd2d2ce48d7ed0e16beb42ac923ccd069701958 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Y...>
Date: Mon, 7 Mar 2022 05:04:16 -0600
Subject: [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.
---
 doc/documentation_guide.rdoc | 21 +++++++++++----------
 1 file 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: https://github.com/ruby/ruby/blob/trunk/doc/documentation_guide.rdoc#L111
 - 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.
 
-- 
cgit v1.2.1


--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/