Document lonely Commits methods

lib/octokit/client/commits.rb

@@ -2,12 +2,27 @@ module Octokit
   class Client
     module Commits
 
-      def commits(repo, branch="master", options={})
-        options = { :per_page => 35, :sha => branch }.merge options
-        get("/repos/#{Repository.new(repo)}/commits", options, 3)
+      # List commits
+      #
+      # Optionally pass <tt>path => "path/to/file.rb"</tt> in <tt>options</tt> to
+      # only return commits containing the given file path.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param sha_or_branch [String] Commit SHA or branch name from which to start the list
+      # @return [Array] An array of hashes representing commits
+      # @see http://developer.github.com/v3/repos/commits/
+      def commits(repo, sha_or_branch="master", options={})
+        params = { :sha => sha_or_branch, :per_page => 35 }
+        get("/repos/#{Repository.new(repo)}/commits", options.merge(params), 3)
       end
       alias :list_commits :commits
 
+      # Get a single commit
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param sha [String] The SHA of the commit to fetch
+      # @return [Hashie::Mash] A hash representing the commit
+      # @see http://developer.github.com/v3/repos/commits/
       def commit(repo, sha, options={})
         get("/repos/#{Repository.new(repo)}/commits/#{sha}", options, 3)
       end
@@ -38,14 +53,31 @@ def create_commit(repo, message, tree, parents=nil, options={})
         post("/repos/#{Repository.new(repo)}/git/commits", options.merge(params), 3)
       end
 
+      # List all commit comments
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @return [Array] An array of hashes representing comments
+      # @see http://developer.github.com/v3/repos/comments/
       def list_commit_comments(repo, options={})
         get("/repos/#{Repository.new(repo)}/comments", options, 3)
       end
 
+      # List comments for a single commit
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param sha [String] The SHA of the commit whose comments will be fetched
+      # @return [Array] An array of hashes representing comments
+      # @see http://developer.github.com/v3/repos/comments/
       def commit_comments(repo, sha, options={})
         get("/repos/#{Repository.new(repo)}/commits/#{sha}/comments", options, 3)
       end
 
+      # Get a single commit comment
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param id [String] The ID of the comment to fetch
+      # @return [Hashie::Mash] A hash representing the comment
+      # @see http://developer.github.com/v3/repos/comments/
       def commit_comment(repo, id, options={})
         get("/repos/#{Repository.new(repo)}/comments/#{id}", options, 3)
       end