aboutsummaryrefslogtreecommitdiffstats
path: root/guides/source/api_documentation_guidelines.md
diff options
context:
space:
mode:
authorburningTyger <b6tyger@gmail.com>2012-11-10 22:18:18 +0100
committerburningTyger <b6tyger@gmail.com>2012-11-10 22:18:18 +0100
commit46100f0ccb189816da91d09c208ea9db9b130a94 (patch)
tree00f10b0c2083bcd9f52b64aed19cd5e88300b384 /guides/source/api_documentation_guidelines.md
parent8553b7ac2f5388271c6c1caaf35c66e997f95cc3 (diff)
downloadrails-46100f0ccb189816da91d09c208ea9db9b130a94.tar.gz
rails-46100f0ccb189816da91d09c208ea9db9b130a94.tar.bz2
rails-46100f0ccb189816da91d09c208ea9db9b130a94.zip
make comments fit the comment boxes (mostly) in API doc guides
Diffstat (limited to 'guides/source/api_documentation_guidelines.md')
-rw-r--r--guides/source/api_documentation_guidelines.md23
1 files changed, 13 insertions, 10 deletions
diff --git a/guides/source/api_documentation_guidelines.md b/guides/source/api_documentation_guidelines.md
index 48b4ddb102..72e412e701 100644
--- a/guides/source/api_documentation_guidelines.md
+++ b/guides/source/api_documentation_guidelines.md
@@ -20,7 +20,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 +52,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"
```
@@ -142,14 +143,16 @@ WARNING: Using a pair of `+...+` for fixed-width font only works with **words**;
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,7 +164,7 @@ 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.