diff options
Diffstat (limited to 'guides/source/api_documentation_guidelines.md')
| -rw-r--r-- | guides/source/api_documentation_guidelines.md | 36 |
1 files changed, 22 insertions, 14 deletions
diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md index dcfa7eb6fb..98ead9570f 100644 --- a/guides/source/api_documentation_guidelines.md +++ b/guides/source/api_documentation_guidelines.md @@ -3,6 +3,11 @@ API Documentation Guidelines This guide documents the Ruby on Rails API documentation guidelines. +After reading this guide, you will know: + +* How to write effective prose for documentation purposes. +* Style guidelines for documenting different kinds of Ruby code. + -------------------------------------------------------------------------------- RDoc @@ -20,7 +25,8 @@ Write in present tense: "Returns a hash that...", rather than "Returned a hash t Start comments in upper case. Follow regular punctuation rules: ```ruby -# Declares an attribute reader backed by an internally-named instance variable. +# Declares an attribute reader backed by an internally-named +# instance variable. def attr_internal_reader(*attrs) ... end @@ -51,8 +57,8 @@ Use two spaces to indent chunks of code--that is, for markup purposes, two space Short docs do not need an explicit "Examples" label to introduce snippets; they just follow paragraphs: ```ruby -# Converts a collection of elements into a formatted string by calling -# `to_s` on all elements and joining them. +# Converts a collection of elements into a formatted string by +# calling +to_s+ on all elements and joining them. # # Blog.all.to_formatted_s # => "First PostSecond PostThird Post" ``` @@ -64,7 +70,7 @@ On the other hand, big chunks of structured documentation may have a separate "E # # Person.exists?(5) # Person.exists?('5') -# Person.exists?(:name => "David") +# Person.exists?(name: "David") # Person.exists?(['name LIKE ?', "%#{query}%"]) ``` @@ -88,7 +94,7 @@ If a line is too long, the comment may be placed on the next line: # label(:post, :title, "A short title") # # => <label for="post_title">A short title</label> # -# label(:post, :title, "A short title", :class => "title_label") +# label(:post, :title, "A short title", class: "title_label") # # => <label for="post_title" class="title_label">A short title</label> ``` @@ -135,21 +141,23 @@ class Array end ``` -WARNING: Using a pair of `+...+` for fixed-width font only works with **words**; that is: anything matching `\A\w+\z`. For anything else use `<tt>...</tt>`, notably symbols, setters, inline snippets, etc. +WARNING: Using a pair of `+...+` for fixed-width font only works with **words**; that is: anything matching `\A\w+\z`. For anything else use `<tt>...</tt>`, notably symbols, setters, inline snippets, etc. ### Regular Font When "true" and "false" are English words rather than Ruby keywords use a regular font: ```ruby -# Runs all the validations within the specified context. Returns true if no errors are found, -# false otherwise. +# Runs all the validations within the specified context. +# Returns true if no errors are found, false otherwise. # -# If the argument is false (default is +nil+), the context is set to <tt>:create</tt> if -# <tt>new_record?</tt> is true, and to <tt>:update</tt> if it is not. +# If the argument is false (default is +nil+), the context is +# set to <tt>:create</tt> if <tt>new_record?</tt> is true, +# and to <tt>:update</tt> if it is not. # -# Validations with no <tt>:on</tt> option will run no matter the context. Validations with -# some <tt>:on</tt> option will only run in the specified context. +# Validations with no <tt>:on</tt> option will run no +# matter the context. Validations with # some <tt>:on</tt> +# option will only run in the specified context. def valid?(context = nil) ... end @@ -161,10 +169,10 @@ Description Lists In lists of options, parameters, etc. use a hyphen between the item and its description (reads better than a colon because normally options are symbols): ```ruby -# * <tt>:allow_nil</tt> - Skip validation if attribute is `nil`. +# * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+. ``` -The description starts in upper case and ends with a full stop—it's standard English. +The description starts in upper case and ends with a full stop-it's standard English. Dynamically Generated Methods ----------------------------- |