Move PermissionsPolicy docs to ActionDispatch::HTTP::PermissionsPolicy [ci-skip]

As most of the PermissionsPolicy is defined in
ActionDispatch::HTTP::PermissionsPolicy, it should include most of the
documentation. ActionController::Metal::PermissionsPolicy should
describe controller overrides.

This PR also makes the documentation more similar to the
ActionDispatch::HTTP::ContentSecurityPolicy documentation.

Note:
The Feature-Policy header has been renamed to Permissions-Policy
in the specification. The Permissions-Policy requires a different
implementation and isn't yet supported by all browsers. To avoid
having to rename this middleware in the future we use the new
name for the middleware but keep the old header name in the
documentation for now.

Co-authored-by: Jonathan Hefner <jonathan@hefner.pro>

actionpack/lib/action_controller/metal/permissions_policy.rb

@@ -1,37 +1,28 @@
 # frozen_string_literal: true
 
 module ActionController # :nodoc:
-  # HTTP Permissions Policy is a web standard for defining a mechanism to
-  # allow and deny the use of browser permissions in its own context, and
-  # in content within any <iframe> elements in the document.
-  #
-  # Full details of HTTP Permissions Policy specification and guidelines can
-  # be found at MDN:
-  #
-  # https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy
-  #
-  # Examples of usage:
-  #
-  #   # Global policy
-  #   Rails.application.config.permissions_policy do |f|
-  #     f.camera      :none
-  #     f.gyroscope   :none
-  #     f.microphone  :none
-  #     f.usb         :none
-  #     f.fullscreen  :self
-  #     f.payment     :self, "https://secure.example.com"
-  #   end
-  #
-  #   # Controller level policy
-  #   class PagesController < ApplicationController
-  #     permissions_policy do |p|
-  #       p.geolocation "https://example.com"
-  #     end
-  #   end
   module PermissionsPolicy
     extend ActiveSupport::Concern
 
     module ClassMethods
+      # Overrides parts of the globally configured Feature-Policy
+      # header:
+      #
+      #   class PagesController < ApplicationController
+      #     permissions_policy do |policy|
+      #       policy.geolocation "https://example.com"
+      #     end
+      #   end
+      #
+      # Options can be passed similar to +before_action+. For example, pass
+      # <tt>only: :index</tt> to override the header on the index action only:
+      #
+      #   class PagesController < ApplicationController
+      #     permissions_policy(only: :index) do |policy|
+      #       policy.camera :self
+      #     end
+      #   end
+      #
       def permissions_policy(**options, &block)
         before_action(options) do
           if block_given?

actionpack/lib/action_dispatch/http/permissions_policy.rb

@@ -3,6 +3,22 @@
 require "active_support/core_ext/object/deep_dup"
 
 module ActionDispatch # :nodoc:
+  # Configures the HTTP
+  # {Feature-Policy}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy]
+  # response header to specify which browser features the current document and
+  # its iframes can use.
+  #
+  # Example global policy:
+  #
+  #   Rails.application.config.permissions_policy do |policy|
+  #     policy.camera      :none
+  #     policy.gyroscope   :none
+  #     policy.microphone  :none
+  #     policy.usb         :none
+  #     policy.fullscreen  :self
+  #     policy.payment     :self, "https://secure.example.com"
+  #   end
+  #
   class PermissionsPolicy
     class Middleware
       CONTENT_TYPE = "Content-Type"