Document available permission sets

This commit adds YARD documentation to the permission sets in
core/lib/spree/permission_sets/.

Closes #5102

core/lib/spree/permission_sets/configuration_display.rb

@@ -2,6 +2,25 @@
 
 module Spree
   module PermissionSets
+    # Read-only permissions for e-commerce settings.
+    #
+    # Roles with this permission will be able to view information, also from the admin
+    # panel, about:
+    #
+    # - Tax categories
+    # - Tax rates
+    # - Zones
+    # - Countries
+    # - States
+    # - Payment methods
+    # - Taxonomies
+    # - Shipping methods
+    # - Shipping categories
+    # - Stock locations
+    # - Stock movements
+    # - Refund reasons
+    # - Reimbursement types
+    # - Return reasons
     class ConfigurationDisplay < PermissionSets::Base
       def activate!
           can [:read, :admin], Spree::TaxCategory

core/lib/spree/permission_sets/configuration_management.rb

@@ -2,6 +2,24 @@
 
 module Spree
   module PermissionSets
+    # Read and write permissions for e-commerce settings.
+    #
+    # Roles with this permission set will have full control over:
+    #
+    # - Tax categories
+    # - Tax rates
+    # - Zones
+    # - Countries
+    # - States
+    # - Payment methods
+    # - Taxonomies
+    # - Shipping methods
+    # - Shipping categories
+    # - Stock locations
+    # - Stock movements
+    # - Refund reasons
+    # - Reimbursement types
+    # - Return reasons
     class ConfigurationManagement < PermissionSets::Base
       def activate!
         can :manage, Spree::TaxCategory

core/lib/spree/permission_sets/dashboard_display.rb

@@ -2,6 +2,11 @@
 
 module Spree
   module PermissionSets
+    # Permissions for viewing the admin dashboard.
+    #
+    # Roles with this permission set will be able to view the admin dashboard,
+    # which may or not contain sensitive information depending on
+    # customizations.
     class DashboardDisplay < PermissionSets::Base
       def activate!
           can [:admin, :home], :dashboards

core/lib/spree/permission_sets/default_customer.rb

@@ -2,6 +2,35 @@
 
 module Spree
   module PermissionSets
+    # Permissions for e-commerce customers.
+    #
+    # This permission set is always added to the `:default` role, which in turn
+    # is the default role for all users without any explicit roles.
+    #
+    # Permissions include reading and updating orders when the ability's user
+    # has been assigned as the order's user, unless the order is already
+    # completed. Same is true for guest checkout orders.
+    #
+    # It grants read-only permissions for the following resources typically used
+    # during a checkout process:
+    #
+    # - Zones
+    # - Countries
+    # - States
+    # - Taxons
+    # - Taxonomies
+    # - Products
+    # - Properties
+    # - Product properties
+    # - Variants
+    # - Option types
+    # - Option values
+    # - Stock items
+    # - Stock locations
+    #
+    # Abilities with this role can also create refund authorizations for orders
+    # with the same user, as well as reading and updating the user record and
+    # their associated cards.
     class DefaultCustomer < PermissionSets::Base
       def activate!
         can :read, Country

core/lib/spree/permission_sets/order_display.rb

@@ -2,6 +2,25 @@
 
 module Spree
   module PermissionSets
+    # Read permissions for orders.
+    #
+    # This permission set allows users to view all related information about
+    # orders, also from the admin panel, including:
+    #
+    # - Orders
+    # - Payments
+    # - Shipments
+    # - Adjustments
+    # - Line items
+    # - Return authorizations
+    # - Customer returns
+    # - Order cancellations
+    # - Reimbursements
+    # - Return items
+    # - Refunds
+    #
+    # However, it does not allow any modifications to be made to any of these
+    # resources.
     class OrderDisplay < PermissionSets::Base
       def activate!
         can [:read, :admin, :edit, :cart], Spree::Order

core/lib/spree/permission_sets/order_management.rb

@@ -2,6 +2,24 @@
 
 module Spree
   module PermissionSets
+    # Full permissions for order management.
+    #
+    # This permission set grants full control over all order and related resources,
+    # including:
+    #
+    # - Orders
+    # - Payments
+    # - Shipments
+    # - Adjustments
+    # - Line items
+    # - Return authorizations
+    # - Customer returns
+    # - Order cancellations
+    # - Reimbursements
+    # - Return items
+    # - Refunds
+    #
+    # It also allows reading reimbursement types, but not modifying them.
     class OrderManagement < PermissionSets::Base
       def activate!
         can :read, Spree::ReimbursementType

core/lib/spree/permission_sets/product_display.rb

@@ -2,6 +2,20 @@
 
 module Spree
   module PermissionSets
+    # Read-only permissions for products.
+    #
+    # This permission set allows users to view all related information about
+    # products, also from the admin panel, including:
+    #
+    # - Products
+    # - Images
+    # - Variants
+    # - Option values
+    # - Product properties
+    # - Option types
+    # - Properties
+    # - Taxonomies
+    # - Taxons
     class ProductDisplay < PermissionSets::Base
       def activate!
         can [:read, :admin, :edit], Spree::Product

core/lib/spree/permission_sets/product_management.rb

@@ -2,6 +2,22 @@
 
 module Spree
   module PermissionSets
+    # Full permissions for product management.
+    #
+    # This permission set grants full control over all product and related resources,
+    # including:
+    #
+    # - Products
+    # - Images
+    # - Variants
+    # - Option values
+    # - Product properties
+    # - Option types
+    # - Properties
+    # - Taxonomies
+    # - Taxons
+    # - Classifications
+    # - Prices
     class ProductManagement < PermissionSets::Base
       def activate!
         can :manage, Spree::Classification

core/lib/spree/permission_sets/promotion_display.rb

@@ -2,6 +2,16 @@
 
 module Spree
   module PermissionSets
+    # Read-only permissions for promotions.
+    #
+    # This permission set allows users to view all related information about
+    # promotions, also from the admin panel, including:
+    #
+    # - Promotions
+    # - Promotion rules
+    # - Promotion actions
+    # - Promotion categories
+    # - Promotion codes
     class PromotionDisplay < PermissionSets::Base
       def activate!
         can [:read, :admin, :edit], Spree::Promotion

core/lib/spree/permission_sets/promotion_management.rb

@@ -2,6 +2,16 @@
 
 module Spree
   module PermissionSets
+    # Full permissions for promotion management.
+    #
+    # This permission set grants full control over all promotion and related resources,
+    # including:
+    #
+    # - Promotions
+    # - Promotion rules
+    # - Promotion actions
+    # - Promotion categories
+    # - Promotion codes
     class PromotionManagement < PermissionSets::Base
       def activate!
         can :manage, Spree::Promotion

core/lib/spree/permission_sets/restricted_stock_display.rb

@@ -2,6 +2,11 @@
 
 module Spree
   module PermissionSets
+    # Read permissions for stock limited to allowed locations.
+    #
+    # This permission set allows users to view information about stock items and
+    # locations, both of them limited to locations they have access to.
+    # Permissions are also granted for the admin panel for items.
     class RestrictedStockDisplay < PermissionSets::Base
       def activate!
         can [:read, :admin], Spree::StockItem, stock_location_id: location_ids

core/lib/spree/permission_sets/restricted_stock_management.rb

@@ -2,6 +2,11 @@
 
 module Spree
   module PermissionSets
+    # Full permissions for stock management limited to allowed locations.
+    #
+    # This permission set grants full control over all stock items a user has
+    # access to their locations. Those locations are also readable by the
+    # corresponding ability.
     class RestrictedStockManagement < PermissionSets::Base
       def activate!
         can :manage, Spree::StockItem, stock_location_id: location_ids

core/lib/spree/permission_sets/stock_display.rb

@@ -2,6 +2,10 @@
 
 module Spree
   module PermissionSets
+    # Read-only permissions for stock.
+    #
+    # This permission set allows users to view information about stock items
+    # (also from the admin panel) and stock locations.
     class StockDisplay < PermissionSets::Base
       def activate!
         can [:read, :admin], Spree::StockItem

core/lib/spree/permission_sets/stock_management.rb

@@ -2,6 +2,10 @@
 
 module Spree
   module PermissionSets
+    # Full permissions for stock management.
+    #
+    # This permission set grants full control over all stock items and read
+    # access to locations.
     class StockManagement < PermissionSets::Base
       def activate!
         can :manage, Spree::StockItem

core/lib/spree/permission_sets/super_user.rb

@@ -2,6 +2,11 @@
 
 module Spree
   module PermissionSets
+    # Full permissions for store administration.
+    #
+    # This permission set is always added to users with the `:admin` role.
+    #
+    # It grants permission to perform any read or write action on any resource.
     class SuperUser < PermissionSets::Base
       def activate!
         can :manage, :all

core/lib/spree/permission_sets/user_display.rb

@@ -2,6 +2,10 @@
 
 module Spree
   module PermissionSets
+    # Read-only permissions for users, roles and store credits.
+    #
+    # This permission set allows users to view all related information about
+    # users, roles and store credits, also from the admin panel.
     class UserDisplay < PermissionSets::Base
       def activate!
         can [:read, :admin, :edit, :addresses, :orders, :items], Spree.user_class

core/lib/spree/permission_sets/user_management.rb

@@ -2,6 +2,15 @@
 
 module Spree
   module PermissionSets
+    # Full permissions for user management.
+    #
+    # This permission set grants full control over all user and
+    # related resources, including:
+    #
+    # - Users
+    # - Store credits
+    # - Roles
+    # - API keys
     class UserManagement < PermissionSets::Base
       def activate!
         can [:admin, :read, :create, :update, :save_in_address_book, :remove_from_address_book, :addresses, :orders, :items], Spree.user_class