From 46100f0ccb189816da91d09c208ea9db9b130a94 Mon Sep 17 00:00:00 2001 From: burningTyger Date: Sat, 10 Nov 2012 22:18:18 +0100 Subject: make comments fit the comment boxes (mostly) in API doc guides --- guides/source/api_documentation_guidelines.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) (limited to 'guides/source') 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 :create if -# new_record? is true, and to :update if it is not. +# If the argument is false (default is +nil+), the context is +# set to :create if new_record? is true, +# and to :update if it is not. # -# Validations with no :on option will run no matter the context. Validations with -# some :on option will only run in the specified context. +# Validations with no :on option will run no +# matter the context. Validations with # some :on +# 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 -# * :allow_nil - Skip validation if attribute is `nil`. +# * :allow_nil - Skip validation if attribute is +nil+. ``` The description starts in upper case and ends with a full stop—it's standard English. -- cgit v1.2.3