From e7f1afbccd3bd7026b7e4f2301beb149ea14a78c Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 15 Jan 2021 14:25:56 -0600 Subject: Additions to method_documentation.rdoc (#4065) * Additions to method_documentation.rdoc --- doc/method_documentation.rdoc | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) (limited to 'doc/method_documentation.rdoc') 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 # => ... 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 {|x| ... }, not {|x| block } or {|x| code }. + +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 \Array. + +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+).. -- cgit v1.2.3