Additions to method_documentation.rdoc (#4065)

* Additions to method_documentation.rdoc

1 files changed, 30 insertions, 2 deletions

diff --git a/doc/method_documentation.rdoc b/doc/method_documentation.rdoc
index 0432216868..83cd1ad632 100644
--- a/doc/method_documentation.rdoc
+++ b/doc/method_documentation.rdoc
@@ -156,9 +156,9 @@ For methods that accept multiple argument types, in some cases it can
 be useful to document the different argument types separately.  It's
 best to use a separate paragraph for each case you are discussing.
 
-== Use of English
+== Use of \English
 
-Readers of this documentation may not be native speakers of English.
+Readers of this documentation may not be native speakers of \English.
 Documentation should be written with this in mind.
 
 Use short sentences and group them into paragraphs that cover a single
@@ -181,3 +181,31 @@ of the method.
 Methods are documented using RDoc syntax.  See the
 {RDoc Markup Reference}[https://docs.ruby-lang.org/en/master/RDoc/Markup.html#class-RDoc::Markup-label-RDoc+Markup+Reference]
 for more information on formatting with RDoc syntax.
+
+=== Output from irb
+
+Consider whether <tt># => ...</tt> in successive codeblock lines should be aligned.
+Alignment may sometimes aid readability.
+
+=== Lists
+
+A list should be preceded by and followed by a blank line.
+This is unnecessary for the HTML output, but helps in the +ri+ output.
+
+=== Call-Seq
+
+A +call-seq+ block should have <tt>{|x| ... }</tt>, not <tt>{|x| block }</tt> or <tt>{|x| code }</tt>.
+
+A +call-seq+ output should:
+- Have +self+, not +receiver+ or +array+.
+- Begin with +new_+ if and only if the output object is a new instance of the receiver's class,
+  to emphasize that the output object is not +self+.
+
+=== Auto-Links
+
+In general, RDoc's auto-linking should not be suppressed.
+For example, we should write +Array+, not <tt>\Array</tt>.
+
+We might consider whether to suppress when:
+- The word in question does not refer to a Ruby class (e.g., some uses of _Class_ or _English_).
+- The reference is to the current class (e.g., _Array_ in the documentation for class +Array+)..