diff --git a/lib/cancan/query.rb b/lib/cancan/query.rb
index 782c7cf..5670cfe 100644
--- a/lib/cancan/query.rb
+++ b/lib/cancan/query.rb
@@ -8,16 +8,21 @@ module CanCan
       @can_definitions = can_definitions
     end
 
-    # Returns a string of SQL conditions which match the ability query.
+    # Returns conditions intended to be used inside a database query. Normally you will not call this
+    # method directly, but instead go through ActiveRecordAdditions#accessible_by.
+    #
+    # If there is only one "can" definition, a hash of conditions will be returned matching the one defined.
+    #
+    #   can :manage, User, :id => 1
+    #   query(:manage, User).conditions # => { :id => 1 }
+    #
+    # If there are multiple "can" definitions, a SQL string will be returned to handle complex cases.
     #
     #   can :manage, User, :id => 1
     #   can :manage, User, :manager_id => 1
     #   cannot :manage, User, :self_managed => true
     #   query(:manage, User).conditions # => "not (self_managed = 't') AND ((manager_id = 1) OR (id = 1))"
     #
-    # Normally you will not call this method directly, but instead go through ActiveRecordAdditions#accessible_by.
-    #
-    # If there is just one :can ability, it conditions returned untouched.
     def conditions
       if @can_definitions.size == 1 && @can_definitions.first.base_behavior
         # Return the conditions directly if there's just one definition
@@ -29,7 +34,7 @@ module CanCan
       end
     end
 
-    # Returns the associations used in conditions for the :joins option of a search
+    # Returns the associations used in conditions for the :joins option of a search.
     # See ActiveRecordAdditions#accessible_by for use in Active Record.
     def joins
       joins_hash = {}
@@ -69,6 +74,7 @@ module CanCan
       @sanitizer.sanitize_sql(conditions)
     end
 
+    # Takes two hashes and does a deep merge.
     def merge_joins(base, add)
       add.each do |name, nested|
         if base[name].is_a?(Hash) && !nested.empty?
@@ -79,6 +85,7 @@ module CanCan
       end
     end
 
+    # Removes empty hashes and moves everything into arrays.
     def clean_joins(joins_hash)
       joins = []
       joins_hash.each do |name, nested|