gists.rb in github_api-0.14.0

- old
+ new

@@ -3,22 +3,17 @@
 module Github
   class Client::Gists < API
 
     require_all 'github_api/client/gists', 'comments'
 
-    REQUIRED_GIST_INPUTS = %w[
-      description
-      public
-      files
-      content
-    ].freeze
-
     # Access to Gists::Comments API
     namespace :comments
 
     # List a user's gists
     #
+    # @see https://developer.github.com/v3/gists/#list-a-users-gists
+    #
     # @example
     #  github = Github.new
     #  github.gists.list user: 'user-name'
     #
     # List the authenticated user’s gists or if called anonymously,
@@ -28,10 +23,12 @@
     #  github = Github.new oauth_token: '...'
     #  github.gists.list
     #
     # List all public gists
     #
+    # @see https://developer.github.com/v3/gists/#list-all-public-gists
+    #
     #  github = Github.new
     #  github.gists.list :public
     #
     # @return [Hash]
     #
@@ -47,17 +44,19 @@
         get_request("/gists", params)
       end
       return response unless block_given?
       response.each { |el| yield el }
     end
-    alias :all :list
+    alias_method :all, :list
 
     # List the authenticated user's starred gists
     #
+    # @see https://developer.github.com/v3/gists/#list-starred-gists
+    #
     # @example
-    #  github = Github.new oauth_token: '...'
-    #  github.gists.starred
+    #   github = Github.new oauth_token: '...'
+    #   github.gists.starred
     #
     # @return [Hash]
     #
     # @api public
     def starred(*args)
@@ -67,26 +66,42 @@
       response.each { |el| yield el }
     end
 
     # Get a single gist
     #
+    # @see https://developer.github.com/v3/gists/#get-a-single-gist
+    #
     # @example
-    #  github = Github.new
-    #  github.gists.get 'gist-id'
+    #   github = Github.new
+    #   github.gists.get 'gist-id'
     #
+    # Get a specific revision of gist
+    #
+    # @see https://developer.github.com/v3/gists/#get-a-specific-revision-of-a-gist
+    #
+    # @example
+    #   github = Github.new
+    #   github.gists.get 'gist-id', sha: '
+    #
     # @return [Hash]
     #
     # @api public
     def get(*args)
       arguments(args, required: [:id])
 
-      get_request("/gists/#{arguments.id}", arguments.params)
+      if (sha = arguments.params.delete('sha'))
+        get_request("/gists/#{arguments.id}/#{sha}")
+      else
+        get_request("/gists/#{arguments.id}", arguments.params)
+      end
     end
-    alias :find :get
+    alias_method :find, :get
 
     # Create a gist
     #
+    # @see https://developer.github.com/v3/gists/#create-a-gist
+    #
     # @param [Hash] params
     # @option params [String] :description
     #   Optional string
     # @option params [Boolean] :public
     #   Required boolean
@@ -110,19 +125,19 @@
     #
     # @return [Hash]
     #
     # @api public
     def create(*args)
-      arguments(args) do
-        assert_required REQUIRED_GIST_INPUTS
-      end
+      arguments(args)
 
       post_request("/gists", arguments.params)
     end
 
     # Edit a gist
     #
+    # @see https://developer.github.com/v3/gists/#edit-a-gist
+    #
     # @param [Hash] params
     # @option [String] :description
     #   Optional string
     # @option [Hash] :files
     #   Optional hash - Files that make up this gist.
@@ -160,10 +175,12 @@
       patch_request("/gists/#{arguments.id}", arguments.params)
     end
 
     # List gist commits
     #
+    # @see https://developer.github.com/v3/gists/#list-gist-commits
+    #
     # @example
     #  github = Github.new
     #  github.gists.commits 'gist-id'
     #
     # @api public
@@ -175,10 +192,12 @@
       response.each { |el| yield el }
     end
 
     # Star a gist
     #
+    # @see https://developer.github.com/v3/gists/#star-a-gist
+    #
     # @example
     #  github = Github.new
     #  github.gists.star 'gist-id'
     #
     # @api public
@@ -188,10 +207,12 @@
       put_request("/gists/#{arguments.id}/star", arguments.params)
     end
 
     # Unstar a gist
     #
+    # @see https://developer.github.com/v3/gists/#unstar-a-gist
+    #
     # @xample
     #  github = Github.new
     #  github.gists.unstar 'gist-id'
     #
     # @api public
@@ -201,14 +222,17 @@
       delete_request("/gists/#{arguments.id}/star", arguments.params)
     end
 
     # Check if a gist is starred
     #
-    # = Examples
-    #  github = Github.new
-    #  github.gists.starred? 'gist-id'
+    # @see https://developer.github.com/v3/gists/#check-if-a-gist-is-starred
     #
+    # @example
+    #   github = Github.new
+    #   github.gists.starred? 'gist-id'
+    #
+    # @api public
     def starred?(*args)
       arguments(args, required: [:id])
       get_request("/gists/#{arguments.id}/star", arguments.params)
       true
     rescue Github::Error::NotFound
@@ -223,18 +247,20 @@
     #
     # @api public
     def fork(*args)
       arguments(args, required: [:id])
 
-      post_request("/gists/#{arguments.id}/fork", arguments.params)
+      post_request("/gists/#{arguments.id}/forks", arguments.params)
     end
 
     # List gist forks
     #
+    # @see https://developer.github.com/v3/gists/#list-gist-forks
+    #
     # @example
-    #  github = Github.new
-    #  github.gists.forks 'gist-id'
+    #   github = Github.new
+    #   github.gists.forks 'gist-id'
     #
     # @api public
     def forks(*args)
       arguments(args, required: [:id])
 
@@ -242,9 +268,11 @@
       return response unless block_given?
       response.each { |el| yield el }
     end
 
     # Delete a gist
+    #
+    # @see https://developer.github.com/v3/gists/#delete-a-gist
     #
     # @example
     #  github = Github.new
     #  github.gists.delete 'gist-id'
     #