diff options
Diffstat (limited to 'railties/guides/source/api_documentation_guidelines.textile')
| -rw-r--r-- | railties/guides/source/api_documentation_guidelines.textile | 32 |
1 files changed, 15 insertions, 17 deletions
diff --git a/railties/guides/source/api_documentation_guidelines.textile b/railties/guides/source/api_documentation_guidelines.textile index e22ffa4c04..99eb668513 100644 --- a/railties/guides/source/api_documentation_guidelines.textile +++ b/railties/guides/source/api_documentation_guidelines.textile @@ -33,12 +33,16 @@ Spell names correctly: Arel, Test::Unit, RSpec, HTML, MySQL, JavaScript, ERB. Wh Use the article "an" for "SQL", as in "an SQL statement". Also "an SQLite database". +h3. English + +Please use American English (<em>color</em>, <em>center</em>, <em>modularize</em>, etc.). See "a list of American and British English spelling differences here":http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences. + h3. Example Code Choose meaningful examples that depict and cover the basics as well as interesting points or gotchas. -Use two spaces to indent chunks of code.—that is two spaces with respect to the left margin; the examples -themselves should use "Rails code conventions":http://rails.lighthouseapp.com/projects/8994/source-style. +Use two spaces to indent chunks of code--that is two spaces with respect to the left margin; the examples +themselves should use "Rails coding conventions":contributing_to_ruby_on_rails.html#follow-the-coding-conventions. Short docs do not need an explicit "Examples" label to introduce snippets, they just follow paragraphs: @@ -74,14 +78,14 @@ The result of expressions follow them and are introduced by "# => ", vertically If a line is too long, the comment may be placed on the next line: <ruby> - # label(:post, :title) - # # => <label for="post_title">Title</label> - # - # label(:post, :title, "A short title") - # # => <label for="post_title">A short title</label> - # - # label(:post, :title, "A short title", :class => "title_label") - # # => <label for="post_title" class="title_label">A short title</label> +# label(:post, :title) +# # => <label for="post_title">Title</label> +# +# label(:post, :title, "A short title") +# # => <label for="post_title">A short title</label> +# +# label(:post, :title, "A short title", :class => "title_label") +# # => <label for="post_title" class="title_label">A short title</label> </ruby> Avoid using any printing methods like +puts+ or +p+ for that purpose. @@ -102,7 +106,6 @@ routes.rb # NO RAILS_ROOT/config/routes.rb # NO </plain> - h3. Fonts h4. Fixed-width Font @@ -143,7 +146,7 @@ h3. 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 <tt>nil</tt>. </ruby> The description starts in upper case and ends with a full stop—it's standard English. @@ -180,8 +183,3 @@ self.class_eval %{ end } </ruby> - -h3. Changelog - -* July 17, 2010: ported from the docrails wiki and revised by "Xavier Noria":credits.html#fxn - |