rewrites the API docs of favicon_link_tag [ci skip]

Motivated by #14907.

1 files changed, 16 insertions, 9 deletions

diff --git a/actionview/lib/action_view/helpers/asset_tag_helper.rb b/actionview/lib/action_view/helpers/asset_tag_helper.rb
index 413532826b..824cdaa45e 100644
--- a/actionview/lib/action_view/helpers/asset_tag_helper.rb
+++ b/actionview/lib/action_view/helpers/asset_tag_helper.rb
@@ -142,22 +142,29 @@ module ActionView
         )
       end
 
-      # Returns a link loading a favicon file. You may specify a different file
-      # in the first argument. The helper accepts an additional options hash where
-      # you can override "rel" and "type".
+      # Returns a link tag for a favicon managed by the asset pipeline.
       #
-      # ==== Options
+      # If a page has no link like the one generated by this helper, browsers
+      # ask for <tt>/favicon.ico</tt> automatically, and cache the file if the
+      # request succeeds. If the favicon changes it is hard to get it updated.
       #
-      # * <tt>:rel</tt>   - Specify the relation of this link, defaults to 'shortcut icon'
-      # * <tt>:type</tt>  - Override the auto-generated mime type, defaults to 'image/x-icon'
+      # To have better control applications may let the asset pipeline manage
+      # their favicon storing the file under <tt>app/assets/images</tt>, and
+      # using this helper to generate its corresponding link tag.
       #
-      # ==== Examples
+      # The helper gets the name of the favicon file as first argument, which
+      # defaults to "favicon.ico", and also supports +:rel+ and +:type+ options
+      # to override their defaults, "shortcut icon" and "image/x-icon"
+      # respectively:
+      #
+      #   favicon_link_tag
+      #   # => <link href="/assets/favicon.ico" rel="shortcut icon" type="image/x-icon" />
       #
       #   favicon_link_tag 'myicon.ico'
       #   # => <link href="/assets/myicon.ico" rel="shortcut icon" type="image/x-icon" />
       #
-      # Mobile Safari looks for a different <link> tag, pointing to an image that
-      # will be used if you add the page to the home screen of an iPod Touch, iPhone, or iPad.
+      # Mobile Safari looks for a different link tag, pointing to an image that
+      # will be used if you add the page to the home screen of an iOS device.
       # The following call would generate such a tag:
       #
       #   favicon_link_tag 'mb-icon.png', rel: 'apple-touch-icon', type: 'image/png'