Improve documentation for find_all, add some for find and add comment…

… saying why commits have to have their repositories set manually.

lib/octopi/commit.rb

@@ -7,32 +7,48 @@ class Commit < Base
     attr_accessor :repository, :message, :parents, :author, :url, :id, :committed_date, :authored_date, :tree, :committer
 
 
-    #Finds all commits for the given options:
+    # Finds all commits for the given options:
     #
     # :repo or :repository or :name - A repository object or the name of a repository
     # :user - A user object or the login of a user
     # :branch - A branch object or the name of a branch. Defaults to master. 
     # 
     # Sample usage:
     #
-    #   find_all(:user => "fcoury", :repo => "octopi") # branch defaults to master
-    #   find_all(:user => "fcoury", :repo => "octopi", :branch => "lazy") # branch is set to lazy.
+    #   >> find_all(:user => "fcoury", :repo => "octopi")
+    #   => <Latest 30 commits for master branch>
+    #  
+    #   => find_all(:user => "fcoury", :repo => "octopi", :branch => "lazy") # branch is set to lazy.
+    #   => <Latest 30 commits for lazy branch>
     #
     def self.find_all(opts={})
-      # TODO: Refactor this into a helper method, is used elsewhere.
       repo = opts[:repository] || opts[:repo] || opts[:name]
       repo = Repository.find(:user => opts[:user], :name => repo) if !repo.is_a?(Repository)
       user = repo.owner.to_s
       user ||= opts[:user].to_s
       branch = opts[:branch] || "master"
       self.validate_args(user => :user, repo.name => :repo)
       commits = super user, repo.name, branch
-      # TODO: Find out what this does, and why it's needed. 
-      # commits.each { |c| c.repository = repo } if repo.is_a? Repository
+      # Repository is not passed in from the data, set it manually.
+      commits.each { |c| c.repository = repo }
       commits
     end
 
-    # Finds a single commit based on the options given
+    # Finds all commits for the given options:
+    #
+    # :repo or :repository or :name - A repository object or the name of a repository
+    # :user - A user object or the login of a user
+    # :branch - A branch object or the name of a branch. Defaults to master. 
+    # :sha - The commit ID
+    # 
+    # Sample usage:
+    #
+    #   >> find(:user => "fcoury", :repo => "octopi", :sha => "f6609209c3ac0badd004512d318bfaa508ea10ae")
+    #   => <Commit f6609209c3ac0badd004512d318bfaa508ea10ae for branch master>
+    #
+    #   >> find(:user => "fcoury", :repo => "octopi", :branch => "lazy", :sha => "f6609209c3ac0badd004512d318bfaa508ea10ae") # branch is set to lazy.
+    #   => <Commit f6609209c3ac0badd004512d318bfaa508ea10ae for branch lazy>
+    #
     def self.find(opts={})
       if args.last.is_a?(Commit)
         commit = args.pop

test/commit_test.rb

@@ -15,6 +15,7 @@ def setup
         commits = Commit.find_all(:user => "fcoury", :repository => "octopi")
         assert_not_nil commits
         assert_equal 30, commits.size
+        assert_not_nil commits.first.repository
       end
 
       should "by objects" do