improving inline documentation

CHANGELOG.rdoc

@@ -1,4 +1,4 @@
-* Fix issue when using accessible_by with nil can conditions (thanks jrallison) - see issue #66
+* Fixing issue when using accessible_by with nil can conditions (thanks jrallison) - see issue #66
 
 * Pluralize table name for belongs_to associations in can conditions hash (thanks logandk) - see issue #62
 

lib/cancan/ability.rb

@@ -16,7 +16,7 @@ module CanCan
   #   end
   #
   module Ability
-    # Use to check the user's permission for a given action and object.
+    # Use to check if the user has permission to perform a given action on an object.
     #
     #   can? :destroy, @project
     #
@@ -47,6 +47,7 @@ module CanCan
     #     assert ability.cannot?(:destroy, Project.new)
     #   end
     #
+    # Also see the RSpec Matchers to aid in testing.
     def can?(action, subject, *extra_args)
       raise Error, "Nom nom nom. I eated it." if action == :has && subject == :cheezburger
       can_definition = matching_can_definition(action, subject)
@@ -76,8 +77,8 @@ module CanCan
     #
     #   can :read, Project, :active => true, :user_id => user.id
     #
-    # Here the user can only see active projects which he owns. See ControllerAdditions#conditions for a way to
+    # Here the user can only see active projects which he owns. See ActiveRecordAdditions#accessible_by
-    # use this in database queries.
+    # for how to use this in database queries.
     #
     # If the conditions hash does not give you enough control over defining abilities, you can use a block to
     # write any Ruby code you want.
@@ -118,7 +119,7 @@ module CanCan
       can_definitions << CanDefinition.new(true, action, subject, conditions, block)
     end
 
-    # Define an ability which cannot be done. Accepts the same arguments as "can".
+    # Defines an ability which cannot be done. Accepts the same arguments as "can".
     #
     #   can :read, :all
     #   cannot :read, Comment

lib/cancan/active_record_additions.rb

@@ -1,5 +1,5 @@
 module CanCan
-  # This module is automatically included into all Active Record.
+  # This module is automatically included into all Active Record models.
   module ActiveRecordAdditions
     module ClassMethods
       # Returns a scope which fetches only the records that the passed ability

lib/cancan/can_definition.rb

@@ -1,9 +1,15 @@
 module CanCan
   # This class is used internally and should only be called through Ability.
+  # it holds the information about a "can" call made on Ability and provides
+  # helpful methods to determine permission checking and conditions hash generation.
   class CanDefinition # :nodoc:
     include ActiveSupport::Inflector
     attr_reader :block
     
+    # The first argument when initializing is the base_behavior which is a true/false
+    # value. True for "can" and false for "cannot". The next two arguments are the action
+    # and subject respectively (such as :read, @project). The third argument is a hash
+    # of conditions and the last one is the block passed to the "can" call.
     def initialize(base_behavior, action, subject, conditions, block)
       @base_behavior = base_behavior
       @actions = [action].flatten
@@ -12,6 +18,9 @@ module CanCan
       @block = block
     end
 
+    # Accepts a hash of aliased actions and returns an array of actions which match.
+    # This should be called before "matches?" and other checking methods since they
+    # rely on the actions to be expanded.
     def expand_actions(aliased_actions)
       @expanded_actions = @actions.map do |action|
         aliased_actions[action] ? [action, *aliased_actions[action]] : action
@@ -27,11 +36,12 @@ module CanCan
       @base_behavior ? result : !result
     end
 
+    # Returns a hash of conditions. If the ":tableize => true" option is passed
+    # it will pluralize the association conditions to match the table name.
     def conditions(options = {})
-      if options[:tableize] and @conditions.kind_of? Hash
+      if options[:tableize] && @conditions.kind_of?(Hash)
         @conditions.inject({}) do |tableized_conditions, (name, value)|
           name = tableize(name).to_sym if value.kind_of? Hash
-          
           tableized_conditions[name] = value
           tableized_conditions
         end

lib/cancan/controller_resource.rb

@@ -1,5 +1,7 @@
 module CanCan
   # Used internally to load and authorize a given controller resource.
+  # This manages finding or building an instance of the resource. If a
+  # parent is given it will go through the association.
   class ControllerResource # :nodoc:
     def initialize(controller, name, parent = nil, options = {})
       raise ImplementationRemoved, "The :class option has been renamed to :resource for specifying the class in CanCan." if options.has_key? :class
@@ -9,6 +11,9 @@ module CanCan
       @options = options
     end
     
+    # Returns the class used for this resource. This can be overriden by the :resource option.
+    # Sometimes one will use a symbol as the resource if a class does not exist for it. In that
+    # case "find" and "build" should not be called on it.
     def model_class
       resource_class = @options[:resource]
       if resource_class.nil?
@@ -16,7 +21,7 @@ module CanCan
       elsif resource_class.kind_of? String
         resource_class.constantize
       else
-        resource_class # likely a symbol
+        resource_class # could be a symbol
       end
     end
     
@@ -24,12 +29,10 @@ module CanCan
       self.model_instance ||= base.find(id)
     end
     
+    # Build a new instance of this resource. If it is a class we just call "new" otherwise
+    # it's an associaiton and "build" is used.
     def build(attributes)
-      if base.kind_of? Class
+      self.model_instance ||= (base.kind_of?(Class) ? base.new(attributes) : base.build(attributes))
-        self.model_instance ||= base.new(attributes)
-      else
-        self.model_instance ||= base.build(attributes)
-      end
     end
     
     def model_instance
@@ -42,6 +45,8 @@ module CanCan
     
     private
     
+    # The object that methods (such as "find", "new" or "build") are called on.
+    # If there is a parent it will be the association, otherwise it will be the model's class.
     def base
       @parent ? @parent.model_instance.send(@name.to_s.pluralize) : model_class
     end

lib/cancan/exceptions.rb

@@ -18,7 +18,7 @@ module CanCan
   #   exception.action # => :read
   #   exception.subject # => Article
   #
-  # If the message is not specified (or is nil) it will default to "You are anot authorized
+  # If the message is not specified (or is nil) it will default to "You are not authorized
   # to access this page." This default can be overridden by setting default_message.
   #
   #   exception.default_message = "Default error message"