Merge pull request #44511 from p8/docs/permission-policy

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

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"