Documenting ApplicationPolicy (#16527)

The comments speak for themselves

Related to #16483

In support of https://github.com/orgs/forem/projects/46

app/policies/application_policy.rb

@@ -1,6 +1,39 @@
+##
+# @abstract
+#
+# The purpose of the ApplicationPolicy is to provide an application specific abstract class that
+# answers questions around authorization to resources.
+#
+# A resource's policy (e.g. Article has an ArticlePolicy) should provide the canonical answer to the
+# question: is the given user authorized to take the given action on the resource (or resource type).
+#
+# @note In an ideal setup our view and controller logic would **never** have the following
+#       construct: `do_it if user.admin?` However we presently have lots of places in our apps and
+#       views that ask those very questions.  An application's views and controllers should rarely
+#       have knowledge about how policies are implemented (e.g. do this if a user has the role).
+#
+# @example
+#   # In a Rails view
+#   <%- if policy(:article).edit? %>
+#     <%= link_to edit_article_path(@article) %>
+#   <%- end %>
+#
+# @example
+#   # In a Rails Controller
+#   def edit
+#     @article = Article.find_by(id: params[:id])
+#     authorize @article
+#   end
+#
+# @see Authorizer for details regarding user roles.
+# @see https://rubygems.org/gems/pundit
 class ApplicationPolicy
   attr_reader :user, :record
 
+  # @param user [User] who's the one taking the action?
+  #
+  # @param record [Class, Object] what is the user acting on?  This could be a model (e.g. Article)
+  #        or an instance of a model (e.g. Article.new) or any Plain Old Ruby Object [PORO].
   def initialize(user, record)
     raise Pundit::NotAuthorizedError, I18n.t("policies.application_policy.you_must_be_logged_in") unless user