controller.rb in trust-0.7.0

- old
+ new

@@ -21,10 +21,11 @@
 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 module Trust
+  # = Trust Controller
   module Controller
     autoload :Resource,           'trust/controller/resource'
     autoload :Properties,         'trust/controller/properties'
     
     extend ActiveSupport::Concern
@@ -47,10 +48,11 @@
       end      
       
       delegate :belongs_to, :actions, :model, :to => :properties
 
       # Enables authorization in controller
+      #
       # +trustee+ accepts +:off+ or a hash of +callback+ options such as +:except+ and +:only+
       #
       # +trustee+ automatically calls the class methods: +set_user+, +load_resource+ and +access_control+
       #
       # +trustee+ will raise an Trust::AccessDenied exception if the user is not permitted the action
@@ -80,12 +82,10 @@
       #   class ApplicationController < ActionController::Base
       #     rescue_from Trust::AccessDenied do |exception|
       #       redirect_to root_url, :alert => exception.message
       #     end
       #   end
-      
-
       def trustee(*args)
         module_eval do
           include TrustInstanceMethods
           set_user *args
           load_resource *args
@@ -93,28 +93,35 @@
           helper_method :can?, :resource
         end
       end
       
       # Enable or disable +before_filter+ callback for setting the current user
-      # Arguments:
+      #
+      # === Arguments:
+      #
       #  :off - switch callback off
       #  :only - only include these actions
       #  :except - except these actions
       def set_user(*args)
         _filter_setting(:set_user, *args)
       end
+      
       # Enable or disable +before_filter+ callback for setting the loading resource
-      # Arguments:
+      #
+      # === Arguments:
+      #
       #  :off - switch callback off
       #  :only - only include these actions
       #  :except - except these actions
       def load_resource(*args)
         _filter_setting(:load_resource, *args)
       end
       # Enable or disable +before_filter+ callback for setting the access control, i.e. verifying permissions
       # for the logged in user
-      # Arguments:
+      #
+      # === Arguments:
+      #
       #  :off - switch callback off
       #  :only - only include these actions
       #  :except - except these actions
       def access_control(*args)
         _filter_setting(:access_control, *args)
@@ -130,11 +137,11 @@
       end
     end
     
     module TrustInstanceMethods
       # Returns the controller Trust::Controller::Properties.
-      # If no properties are instantiated, it will be instantiated
+      # If no properties are instantiated, it will be instantiated.
       # 
       # == Delegated methods
       #
       # The following methods are delegated to properties. See Trust::Controller::Properties for details
       # * <tt>belongs_to</tt> - define one or more associations to parents
@@ -144,12 +151,13 @@
       #
       def properties
         self.class.properties
       end
       
-      # Sets the current user. It assumes +current_user+ is defined
-      # This method is triggered as a callback on +before_filter+
+      # Sets the current user. It assumes +current_user+ is defined.
+      #
+      # This method is triggered as a callback on +before_filter+.
       # You may override this method.
       #
       # ==== Example
       # 
       #   def set_user
@@ -158,31 +166,35 @@
       def set_user
         Trust::Authorization.user = current_user
       end
 
       # Returns the Trust::Controller::Resource resource for the controller.
-      # Available as a helper in views
-      # See Trust::Controller::Resource for relevant methods
+      #
+      # Available as a helper in views.
+      # See {Trust::Controller::Resource} for relevant methods.
       def resource
         @resource ||= Trust::Controller::Resource.new(self, self.class.properties, action_name, params, request)
       end
       
       # Loads the resource which basically means loading the instance and eventual parent defined through +belongs_to+
+      #
       # This method is triggered as a callback on +before_filter+
-      # See Trust::Controller::Resource for more information
+      # See {Trust::Controller::Resource} for more information
       def load_resource
         resource.load
       end
       
-      # Performs the actual access_control
+      # Performs the actual access_control.
+      #
       # This method is triggered as a callback on +before_filter+
       def access_control
         Trust::Authorization.authorize!(action_name, resource.instance || resource.klass, resource.parent)
       end
 
-      # Tests for current users permissions
+      # Tests for current users permissions.
+      #
       # If access control is not sufficient in controller, you may use this method.
-      # Also available as a helper in views
+      # Also available as a helper in views.
       #
       # ==== Examples
       #   can? :edit                          # does the current user have permission to edit the current resource? 
       #                                       # If there is a nested resource, the parent is automatically associated
       #   can? :edit, @customer               # does the current user have permission to edit the given customer? 