Fully document asset_path.

actionview/lib/action_view/helpers/asset_url_helper.rb

@@ -118,16 +118,67 @@ module ActionView
     module AssetUrlHelper
       URI_REGEXP = %r{^[-a-z]+://|^(?:cid|data):|^//}i
 
-      # Computes the path to asset in public directory. If :type
-      # options is set, a file extension will be appended and scoped
-      # to the corresponding public directory.
+      # This is the entry point for all assets.
+      # When using the asset pipeline (i.e. sprockets and sprockets-rails), the
+      # behavior is "enhanced". You can bypass the asset pipeline by passing in
+      # `public_folder: true` to the options.
       #
       # All other asset *_path helpers delegate through this method.
       #
-      #   asset_path "application.js"                     # => /assets/application.js
-      #   asset_path "application", type: :javascript     # => /assets/application.js
-      #   asset_path "application", type: :stylesheet     # => /assets/application.css
-      #   asset_path "http://www.example.com/js/xmlhr.js" # => http://www.example.com/js/xmlhr.js
+      # === With the asset pipeline
+      #
+      # All options passed to asset_path will be passed to `compute_asset_path
+      # which is implemented by sprockets-rails.
+      #
+      #      asset_path("application.js") # => "/assets/application-60aa4fdc5cea14baf5400fba1abf4f2a46a5166bad4772b1effe341570f07de9.js"
+      #
+      # === Without the asset pipeline (`public_folder: true`)
+      #
+      # Accepts a `type` option that can specify the asset's extension. No error
+      # checking is done to verify the source passed into `asset_path` is valid
+      # and that the file exists on disk.
+      #
+      #      asset_path("application.js", public_folder: true)                 # => "application.js"
+      #      asset_path("filedoesnotexist.png", public_folder: true)           # => "filedoesnotexist.png"
+      #      asset_path("application", type: :javascript, public_folder: true) # => "/javascripts/application.js"
+      #      asset_path("application", type: :stylesheet, public_folder: true) # => "/stylesheets/application.css"
+      #
+      # === Options applying to all assets
+      #
+      # Below lists scenarios that apply to `asset_path` whether or not you're
+      # using the asset pipeline.
+      #
+      # - All fully qualified urls are returned immediately. This bypasses the
+      #   asset pipeline and all other behavior described.
+      #
+      #     asset_path("http://www.example.com/js/xmlhr.js") # => "http://www.example.com/js/xmlhr.js"
+      #
+      # - All assets that begin with a forward slash are assumed to be full
+      #   urls and will not be expanded. This will bypass the asset pipeline.
+      #
+      #     asset_path("/foo.png") # => "/foo.png"
+      #
+      # - All blank strings will be returned immediately. This bypasses the
+      #   asset pipeline and all other behavior described.
+      #
+      #     asset_path("") # => ""
+      #
+      # - If `config.relative_url_root` is specified, all assets will have that
+      #   root prepended.
+      #
+      #     Rails.application.config.relative_url_root = "bar"
+      #     asset_path("foo.js", public_folder: true) # => "bar/foo.js"
+      #
+      # - A different asset host can be specified via `config.action_controller.asset_host`
+      #   this is commonly used in conjunction with a CDN.
+      #
+      #     Rails.application.config.action_controller.asset_host = "assets.example.com"
+      #     asset_path("foo.js", public_folder: true) # => "http://assets.example.com/foo.js"
+      #
+      # - An extension name can be specified manually with `extname`.
+      #
+      #     asset_path("foo", public_folder: true, extname: ".js")     # => "/foo.js"
+      #     asset_path("foo.css", public_folder: true, extname: ".js") # => "/foo.css.js"
       def asset_path(source, options = {})
         raise ArgumentError, "nil is not a valid asset source" if source.nil?