Correct translate helper docs [ci skip]

The documentation previously stated that calling `translate(".foo")` was
equivalent to calling `I18n.translate("people.index.foo")` which is
incorrect due to the various other functions of the `translate` view
helper. This has been fixed.

Additionally, a note about forcing the view helper to re-raise
exceptions was added to the section detailing the handling of missing
translations.

Other cleanup includes:

* Consistent formatting of code
* Stop indenting bulleted list as a code sample
* Tighten some of the language
* Wrap at 80 characters.

1 files changed, 36 insertions, 23 deletions

diff --git a/actionview/lib/action_view/helpers/translation_helper.rb b/actionview/lib/action_view/helpers/translation_helper.rb
index 9d7390f1fd..089627a221 100644
--- a/actionview/lib/action_view/helpers/translation_helper.rb
+++ b/actionview/lib/action_view/helpers/translation_helper.rb
@@ -7,34 +7,47 @@ module ActionView
   module Helpers
     module TranslationHelper
       include TagHelper
-      # Delegates to <tt>I18n#translate</tt> but also performs three additional functions.
+      # Delegates to <tt>I18n#translate</tt> but also performs three additional
+      # functions.
       #
-      # First, it will ensure that any thrown +MissingTranslation+ messages will be turned
-      # into inline spans that:
+      # First, it will ensure that any thrown +MissingTranslation+ messages will
+      # be rendered as inline spans that:
       #
-      #   * have a "translation-missing" class set,
-      #   * contain the missing key as a title attribute and
-      #   * a titleized version of the last key segment as a text.
+      # * Have a <tt>translation-missing</tt> class applied
+      # * Contain the missing key as the value of the +title+ attribute
+      # * Have a titleized version of the last key segment as text
       #
-      # E.g. the value returned for a missing translation key :"blog.post.title" will be
-      # <span class="translation_missing" title="translation missing: en.blog.post.title">Title</span>.
-      # This way your views will display rather reasonable strings but it will still
-      # be easy to spot missing translations.
+      # For example, the value returned for the missing translation key
+      # <tt>"blog.post.title"</tt> will be:
       #
-      # Second, it'll scope the key by the current partial if the key starts
-      # with a period. So if you call <tt>translate(".foo")</tt> from the
-      # <tt>people/index.html.erb</tt> template, you'll actually be calling
-      # <tt>I18n.translate("people.index.foo")</tt>. This makes it less repetitive
-      # to translate many keys within the same partials and gives you a simple framework
-      # for scoping them consistently. If you don't prepend the key with a period,
-      # nothing is converted.
+      #    <span
+      #      class="translation_missing"
+      #      title="translation missing: en.blog.post.title">Title</span>
       #
-      # Third, it'll mark the translation as safe HTML if the key has the suffix
-      # "_html" or the last element of the key is the word "html". For example,
-      # calling translate("footer_html") or translate("footer.html") will return
-      # a safe HTML string that won't be escaped by other HTML helper methods. This
-      # naming convention helps to identify translations that include HTML tags so that
-      # you know what kind of output to expect when you call translate in a template.
+      # This allows for views to display rather reasonable strings while still
+      # giving developers a way to find missing translations.
+      #
+      # If you would prefer missing translations to raise an error, you can
+      # opt out of span-wrapping behavior globally by setting
+      # <tt>ActionView::Base.raise_on_missing_translations = true</tt> or
+      # individually by passing <tt>raise: true</tt> as an option to
+      # <tt>translate</tt>.
+      #
+      # Second, if the key starts with a period <tt>translate</tt> will scope
+      # the key by the current partial. Calling <tt>translate(".foo")</tt> from
+      # the <tt>people/index.html.erb</tt> template is equivalent to calling
+      # <tt>translate("people.index.foo")</tt>. This makes it less
+      # repetitive to translate many keys within the same partial and provides
+      # a convention to scope keys consistently.
+      #
+      # Third, the translation will be marked as <tt>html_safe</tt> if the key
+      # has the suffix "_html" or the last element of the key is "html". Calling
+      # <tt>translate("footer_html")</tt> or <tt>translate("footer.html")</tt>
+      # will return an HTML safe string that won't be escaped by other HTML
+      # helper methods. This naming convention helps to identify translations
+      # that include HTML tags so that you know what kind of output to expect
+      # when you call translate in a template and translators know which keys
+      # they can provide HTML values for.
       def translate(key, options = {})
         options = options.dup
         has_default = options.has_key?(:default)