make comments fit the comment boxes (mostly) in API doc guides

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.