Merge pull request #858 from varvet/kbs/janitor-2

Update inline code documentation

Author: Burgestrand

lib/pundit.rb

@@ -3,83 +3,30 @@
 require "active_support"
 
 require "pundit/version"
+require "pundit/error"
 require "pundit/policy_finder"
-require "pundit/authorization"
 require "pundit/context"
+require "pundit/authorization"
+require "pundit/helper"
 require "pundit/cache_store"
 require "pundit/cache_store/null_store"
 require "pundit/cache_store/legacy_store"
 require "pundit/railtie" if defined?(Rails)
 
-# @api private
-# To avoid name clashes with common Error naming when mixing in Pundit,
-# keep it here with compact class style definition.
-class Pundit::Error < StandardError; end # rubocop:disable Style/ClassAndModuleChildren
-
 # Hello? Yes, this is Pundit.
 #
 # @api public
 module Pundit
   # @api private
+  # @since v1.0.0
   # @deprecated See {Pundit::PolicyFinder}
   SUFFIX = Pundit::PolicyFinder::SUFFIX
 
   # @api private
   # @private
+  # @since v0.1.0
   module Generators; end
 
-  # Error that will be raised when authorization has failed
-  class NotAuthorizedError < Error
-    # @see #initialize
-    attr_reader :query
-    # @see #initialize
-    attr_reader :record
-    # @see #initialize
-    attr_reader :policy
-
-    # @overload initialize(message)
-    #   Create an error with a simple error message.
-    #   @param [String] message A simple error message string.
-    #
-    # @overload initialize(options)
-    #   Create an error with the specified attributes.
-    #   @param [Hash] options The error options.
-    #   @option options [String] :message Optional custom error message. Will default to a generalized message.
-    #   @option options [Symbol] :query The name of the policy method that was checked.
-    #   @option options [Object] :record The object that was being checked with the policy.
-    #   @option options [Class] :policy The class of policy that was used for the check.
-    def initialize(options = {})
-      if options.is_a? String
-        message = options
-      else
-        @query  = options[:query]
-        @record = options[:record]
-        @policy = options[:policy]
-
-        message = options.fetch(:message) do
-          record_name = record.is_a?(Class) ? record.to_s : "this #{record.class}"
-          "not allowed to #{policy.class}##{query} #{record_name}"
-        end
-      end
-
-      super(message)
-    end
-  end
-
-  # Error that will be raised if a policy or policy scope constructor is not called correctly.
-  class InvalidConstructorError < Error; end
-
-  # Error that will be raised if a controller action has not called the
-  # `authorize` or `skip_authorization` methods.
-  class AuthorizationNotPerformedError < Error; end
-
-  # Error that will be raised if a controller action has not called the
-  # `policy_scope` or `skip_policy_scope` methods.
-  class PolicyScopingNotPerformedError < AuthorizationNotPerformedError; end
-
-  # Error that will be raised if a policy or policy scope is not defined.
-  class NotDefinedError < Error; end
-
   def self.included(base)
     location = caller_locations(1, 1).first
     warn <<~WARNING
@@ -91,6 +38,7 @@ def self.included(base)
 
   class << self
     # @see Pundit::Context#authorize
+    # @since v1.0.0
     def authorize(user, record, query, policy_class: nil, cache: nil)
       context = if cache
         policy_cache = CacheStore::LegacyStore.new(cache)
@@ -103,34 +51,27 @@ def authorize(user, record, query, policy_class: nil, cache: nil)
     end
 
     # @see Pundit::Context#policy_scope
+    # @since v0.1.0
     def policy_scope(user, *args, **kwargs, &block)
       Context.new(user: user).policy_scope(*args, **kwargs, &block)
     end
 
     # @see Pundit::Context#policy_scope!
+    # @since v0.1.0
     def policy_scope!(user, *args, **kwargs, &block)
       Context.new(user: user).policy_scope!(*args, **kwargs, &block)
     end
 
     # @see Pundit::Context#policy
+    # @since v0.1.0
     def policy(user, *args, **kwargs, &block)
       Context.new(user: user).policy(*args, **kwargs, &block)
     end
 
     # @see Pundit::Context#policy!
+    # @since v0.1.0
     def policy!(user, *args, **kwargs, &block)
       Context.new(user: user).policy!(*args, **kwargs, &block)
     end
   end
-
-  # Rails view helpers, to allow a slightly different view-specific
-  # implementation of the methods in {Pundit::Authorization}.
-  #
-  # @api private
-  module Helper
-    # @see Pundit::Authorization#pundit_policy_scope
-    def policy_scope(scope)
-      pundit_policy_scope(scope)
-    end
-  end
 end

lib/pundit/authorization.rb

@@ -9,6 +9,7 @@ module Pundit
   #   end
   # @see #pundit
   # @api public
+  # @since v2.2.0
   module Authorization
     extend ActiveSupport::Concern
 
@@ -30,6 +31,7 @@ module Authorization
     # @return [Pundit::Context]
     # @see #pundit_user
     # @see #policies
+    # @since v2.3.2
     def pundit
       @pundit ||= Pundit::Context.new(
         user: pundit_user,
@@ -45,6 +47,7 @@ def pundit
     # @see #pundit
     # @see #pundit_reset!
     # @return [Object] the user object to be used with pundit
+    # @since v0.2.2
     def pundit_user
       current_user
     end
@@ -59,6 +62,7 @@ def pundit_user
     # with the correct context for the new pundit_user.
     #
     # @return [void]
+    # @since v2.5.0
     def pundit_reset!
       @pundit = nil
       @_pundit_policies = nil
@@ -81,6 +85,7 @@ def pundit_reset!
     # @return [record] Always returns the passed object record
     # @see Pundit::Context#authorize
     # @see #verify_authorized
+    # @since v0.1.0
     def authorize(record, query = nil, policy_class: nil)
       query ||= "#{action_name}?"
 
@@ -94,13 +99,15 @@ def authorize(record, query = nil, policy_class: nil)
     # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
     # @return [void]
     # @see #verify_authorized
+    # @since v1.0.0
     def skip_authorization
       @_pundit_policy_authorized = :skipped
     end
 
     # @return [Boolean] wether or not authorization has been performed
     # @see #authorize
     # @see #skip_authorization
+    # @since v1.0.0
     def pundit_policy_authorized?
       !!@_pundit_policy_authorized
     end
@@ -115,6 +122,7 @@ def pundit_policy_authorized?
     # @return [void]
     # @see #authorize
     # @see #skip_authorization
+    # @since v0.1.0
     def verify_authorized
       raise AuthorizationNotPerformedError, self.class unless pundit_policy_authorized?
     end
@@ -124,6 +132,7 @@ def verify_authorized
     # Cache of policies. You should not rely on this method.
     #
     # @api private
+    # @since v1.0.0
     def policies
       @_pundit_policies ||= {}
     end
@@ -137,6 +146,7 @@ def policies
     # @see https://github.com/varvet/pundit#policies
     # @param record [Object] the object we're retrieving the policy for
     # @return [Object] instance of policy class with query methods
+    # @since v0.1.0
     def policy(record)
       pundit.policy!(record)
     end
@@ -149,6 +159,7 @@ def policy(record)
     # @param scope [Object] the object we're retrieving the policy scope for
     # @param policy_scope_class [#resolve] the policy scope class we want to force use of
     # @return [#resolve, nil] instance of scope class which can resolve to a scope
+    # @since v0.1.0
     def policy_scope(scope, policy_scope_class: nil)
       @_pundit_policy_scoped = true
       policy_scope_class ? policy_scope_class.new(pundit_user, scope).resolve : pundit_policy_scope(scope)
@@ -159,13 +170,15 @@ def policy_scope(scope, policy_scope_class: nil)
     # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
     # @return [void]
     # @see #verify_policy_scoped
+    # @since v1.0.0
     def skip_policy_scope
       @_pundit_policy_scoped = :skipped
     end
 
     # @return [Boolean] wether or not policy scoping has been performed
     # @see #policy_scope
     # @see #skip_policy_scope
+    # @since v1.0.0
     def pundit_policy_scoped?
       !!@_pundit_policy_scoped
     end
@@ -181,6 +194,7 @@ def pundit_policy_scoped?
     # @return [void]
     # @see #policy_scope
     # @see #skip_policy_scope
+    # @since v0.2.1
     def verify_policy_scoped
       raise PolicyScopingNotPerformedError, self.class unless pundit_policy_scoped?
     end
@@ -190,6 +204,7 @@ def verify_policy_scoped
     # Cache of policy scope. You should not rely on this method.
     #
     # @api private
+    # @since v1.0.0
     def policy_scopes
       @_pundit_policy_scopes ||= {}
     end
@@ -206,6 +221,7 @@ def policy_scopes
     # @note This also memoizes the instance with `scope` as the key.
     # @see Pundit::Helper#policy_scope
     # @api private
+    # @since v1.0.0
     def pundit_policy_scope(scope)
       policy_scopes[scope] ||= pundit.policy_scope!(scope)
     end
@@ -228,6 +244,7 @@ def pundit_policy_scope(scope)
     # @param action [Symbol, String] the name of the action being performed on the record (e.g. `:update`).
     #   If omitted then this defaults to the Rails controller action name.
     # @return [Hash{String => Object}] the permitted attributes
+    # @since v1.0.0
     def permitted_attributes(record, action = action_name)
       policy = policy(record)
       method_name = if policy.respond_to?("permitted_attributes_for_#{action}")
@@ -242,6 +259,7 @@ def permitted_attributes(record, action = action_name)
     #
     # @param record [Object] the object we're retrieving params for
     # @return [ActionController::Parameters] the params
+    # @since v2.0.0
     def pundit_params_for(record)
       params.require(PolicyFinder.new(record).param_key)
     end

lib/pundit/cache_store.rb

@@ -5,12 +5,14 @@ module Pundit
   #
   # Cache stores are used to cache policy lookups, so you get the same policy
   # instance for the same record.
+  # @since v2.3.2
   module CacheStore
     # @!group Cache Store Interface
 
     # @!method fetch(user:, record:, &block)
     #   Looks up a stored policy or generate a new one.
     #
+    #   @since v2.3.2
     #   @note This is a method template, but the method does not exist in this module.
     #   @param user [Object]  the user that initiated the action
     #   @param record [Object] the object being accessed

lib/pundit/cache_store/legacy_store.rb

@@ -7,14 +7,17 @@ module CacheStore
     # The original cache mechanism used by Pundit.
     #
     # @api private
+    # @since v2.3.2
     class LegacyStore
+      # @since v2.3.2
       def initialize(hash = {})
         @store = hash
       end
 
       # A cache store that uses only the record as a cache key, and ignores the user.
       #
       # @note `nil` results are not cached.
+      # @since v2.3.2
       def fetch(user:, record:)
         _ = user
         @store[record] ||= yield

lib/pundit/cache_store/null_store.rb

@@ -8,17 +8,20 @@ module CacheStore
     #
     # @see Pundit::Context#initialize
     # @api private
+    # @since v2.3.2
     class NullStore
       @instance = new
 
       class << self
+        # @since v2.3.2
         # @return [NullStore] the singleton instance
         attr_reader :instance
       end
 
       # Always yields, does not cache anything.
       # @yield
       # @return [any] whatever the block returns.
+      # @since v2.3.2
       def fetch(*, **)
         yield
       end