summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorBurdette Lamar <BurdetteLamar@Yahoo.com>2021-01-15 14:25:56 -0600
committerGitHub <noreply@github.com>2021-01-15 14:25:56 -0600
commite7f1afbccd3bd7026b7e4f2301beb149ea14a78c (patch)
treee7e489fa1712dd7fa4fc84c4606a08aabe390972 /doc
parenta2941d71342a7401763c77b1c5ba0eace4461a14 (diff)
Additions to method_documentation.rdoc (#4065)
* Additions to method_documentation.rdoc
Notes
Notes: Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
Diffstat (limited to 'doc')
-rw-r--r--doc/method_documentation.rdoc32
1 files changed, 30 insertions, 2 deletions
diff --git a/doc/method_documentation.rdoc b/doc/method_documentation.rdoc
index 0432216..83cd1ad 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+)..