RubyGems - box-api - Versions diffs - 0.1.7 → 0.1.8 - Mend

box-api 0.1.7 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (50) hide show

data/Gemfile.lock +1 -1
data/box-api.gemspec +1 -1
data/doc/Box.html +108 -0
data/doc/Box/Account.html +1099 -0
data/doc/Box/Api.html +3428 -0
data/doc/Box/Api/AccountExceeded.html +130 -0
data/doc/Box/Api/EmailInvalid.html +141 -0
data/doc/Box/Api/EmailTaken.html +130 -0
data/doc/Box/Api/ErrorStatus.html +130 -0
data/doc/Box/Api/Exception.html +120 -0
data/doc/Box/Api/Generic.html +130 -0
data/doc/Box/Api/InvalidFolder.html +141 -0
data/doc/Box/Api/InvalidInput.html +130 -0
data/doc/Box/Api/InvalidName.html +130 -0
data/doc/Box/Api/NameTaken.html +130 -0
data/doc/Box/Api/NoAccess.html +130 -0
data/doc/Box/Api/NoParent.html +130 -0
data/doc/Box/Api/NotAuthorized.html +130 -0
data/doc/Box/Api/Restricted.html +141 -0
data/doc/Box/Api/SizeExceeded.html +130 -0
data/doc/Box/Api/Unknown.html +130 -0
data/doc/Box/Api/UnknownResponse.html +141 -0
data/doc/Box/Api/UploadFailed.html +141 -0
data/doc/Box/File.html +580 -0
data/doc/Box/Folder.html +1078 -0
data/doc/Box/Item.html +1884 -0
data/doc/_index.html +342 -0
data/doc/class_list.html +47 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +53 -0
data/doc/css/style.css +320 -0
data/doc/file.README.html +98 -0
data/doc/file_list.html +49 -0
data/doc/frames.html +13 -0
data/doc/index.html +98 -0
data/doc/js/app.js +205 -0
data/doc/js/full_list.js +150 -0
data/doc/js/jquery.js +16 -0
data/doc/method_list.html +574 -0
data/doc/top-level-namespace.html +103 -0
data/examples/login.rb +4 -4
data/lib/box/account.rb +168 -51
data/lib/box/api.rb +174 -16
data/lib/box/api/exceptions.rb +4 -0
data/lib/box/file.rb +17 -4
data/lib/box/folder.rb +85 -30
data/lib/box/item.rb +89 -20
data/spec/account_spec.rb +0 -4
data/spec/folder_spec.rb +3 -9
metadata +42 -4

data/doc/top-level-namespace.html ADDED

@@ -0,0 +1,103 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.7.2
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
+<script type="text/javascript" charset="utf-8">
+  relpath = '';
+  if (relpath != '') relpath += '/';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <script type="text/javascript" charset="utf-8">
+      if (window.top.frames.main) document.body.className = 'frames';
+    </script>
+    <div id="header">
+      <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
+</div>
+      <div id="search">
+    <a id="class_list_link" href="#">Class List</a>
+    <a id="method_list_link" href="#">Method List</a>
+    <a id="file_list_link" href="#">File List</a>
+</div>
+      <div class="clear"></div>
+    </div>
+    <iframe id="search_frame"></iframe>
+    <div id="content"><h1>Top Level Namespace
+</h1>
+<dl class="box">
+</dl>
+<div class="clear"></div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Box.html" title="Box (module)">Box</a></span>
+</p>
+</div>
+    <div id="footer">
+  Generated on Mon Aug  8 13:05:22 2011 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.7.2 (ruby-1.9.2).
+</div>
+  </body>
+</html>

data/examples/login.rb CHANGED

@@ -24,19 +24,19 @@ account = Box::Account.new(app_data['api_key'])
 auth_token = app_data['auth_token']
 # now we have enough information to log into the box api, so we try to authorize using the auth token
-authed = account.authorize(auth_token) do |auth_url|
+account.authorize(auth_token) do |auth_url|
   # this block is called if the auth_token is invalid or missing
   # we use launchy to open a new browser, but you can do it however you want
   Launchy.open(auth_url)
   # make sure you pause until the user has authorized, or just tell them to restart the program
-  puts "Hit any key once you have logged in on the opened web page."
+  puts "Please press the enter key once you have authorized this application to use your account"
   gets
 end
-unless authed
-  # the user didn't auth like we told them to, so we can't access anything
+unless account.authorized?
+  # the user didn't authorize like we told them to, so we can't access anything
   puts "Unable to login, please try again."
   exit
 end

data/lib/box/account.rb CHANGED

@@ -2,32 +2,111 @@ require 'box/api'
 require 'box/folder'
 module Box
-  class Account
-    attr_reader :api, :ticket, :auth_token
+  # Represents an account on Box. In order to use the Box api, the user
+  # must first grant the application permission to use their account. This
+  # is done in the {#authorize} function. Once an account has been
+  # authorized, it can access all of the details and information stored
+  # on that account.
-    # setup the api using our api_key
+  class Account
+    # @return [String] The auth token if authorization was successful.
+    attr_reader :auth_token
+    # Creates an account object using the given Box api key.
+    # You can then {#register} a new account or {#authorize} an
+    # existing account.
+    #
+    # @param [String, Api] api the api key to use for the Box api.
     def initialize(api)
       @api = case
         when api.class == Box::Api; api # use the api object as passed in
-        else; Box::Api.new(api) # allows user to pass in the api_key rather than make a new API object themselves
+        else; Box::Api.new(api) # allows user to pass in a string
       end
     end
-    #### AUTHENTICATION SECTION ####
-    # register the user with the given details
+    # Register a new account on the Box website with the given details.
+    #
+    # @param [String] email The email address to create the account with
+    # @param [String] password The password to create the account with
+    # @return [Boolean] Whether registration was successful.
+    #
+    # @raise [Api::EmailInvalid] The email address was invalid
+    # @raise [Api::EmailTaken] The email address was taken
+    #
     def register(email, password)
-      # note: this function can throw EmailInvalid and EmailTaken
       response = @api.register_new_user(email, password)
-      cache_info(response['user']) # cache account_info, saves an extra API call
+      cache_info(response['user']) # cache account_info, saving an extra API call
       authorize_token(response['token'])
+      true
+    end
+    # Authorize the account using the given auth token, or request
+    # permission from the user to let this application use their account.
+    #
+    # An auth token can be reused from previous authorizations provided the
+    # user doesn't log out, and significantly speeds up the process. If the
+    # auth token if invalid or not provided, the account tries to log in
+    # normally and requires the user to log in and provide access for their
+    # account.
+    #
+    # @param [Optional, String] auth_token Uses an existing token or requests
+    #        a new one if nil.
+    # @yield [authorize_url] This block called when the user has not yet
+    #        granted this application permission to use their account. You
+    #        must have the user navigate to the passed url and authorize
+    #        this app before continuing.
+    # @return [Boolean] Whether the user is authorized.
+    #
+    # @example Authorize an account without a saved auth token.
+    #   account.authorize do |auth_url|
+    #     puts "Please visit #{ auth_url } and enter your account infomation"
+    #     puts "Press the enter key once you have done this."
+    #     gets # wait for the enter key to be pressed
+    #   end
+    #
+    # @example Authorize an account using an existing auth token.
+    #   auth_token = "saved auth token" # load from file ideally
+    #   account.authorize(auth_token)
+    #
+    # @example Combining the above two for the best functionality.
+    #   auth_token = "saved auth token" # load from file if possible
+    #   account.authorize(auth_token) do |auth_url|
+    #     # auth token was invalid or nil, have the user visit auth_url
+    #   end
+    #
+    def authorize(auth_token = nil)
+      # use a saved auth token if it is given
+      if auth_token
+        return true if authorize_token(auth_token)
+      end
+      # the auth token either failed or was not provided
+      # we must try to authorize a ticket, and call the block if that fails
+      if not authorize_ticket and block_given?
+        # the supplied block should instruct the user to visit this url
+        yield authorize_url
+        # try authorizing once more
+        authorize_ticket
+      end
+      # return our authorized status
+      authorized?
     end
-    # logout, rendering any auth_token useless
+    # Log out of the account and invalidate the auth token.
+    #
+    # @note The user will have to re-authorize if they wish to use this
+    #       application, and the auth token will no longer work.
+    #
+    # @return [Boolean] Whether logout was successful.
+    #
     def logout
       begin
         @api.logout
-        authorize_token(nil)
+        cache_token(nil)
       rescue Api::NotAuthorized
         # already logged out, or never logged in
       end
@@ -35,72 +114,110 @@ module Box
       true
     end
-    # authorize the application either using a saved auth_token or ask for a new token
-    def authorize(auth_token = self.auth_token)
-      return true if auth_token and authorize_token(auth_token) # saved auth_tokens significantly speed up the authentication process
+    # Return the account details. A cached copy will be used if avaliable,
+    # and requested if it is not.
+    #
+    # @param [Boolean] refresh Will not use the cached version if true.
+    # @return [Hash] A hash containing all of the user's account
+    #         details, or nil if they are not authorized. Please see the
+    #         Box api documentation for information about each field.
+    #
+    # TODO: Add url to Box api documentation, and provide the current fields.
+    #
+    def info(refresh = false)
+      return @info if @info and not refresh
-      if block_given? and not authorize_ticket # if we cannot authorize the ticket, the user needs to visit a web page and give our app permission
-        yield authorize_url # the supplied block should instruct the user to visit this url, returning once they have
-        authorize_ticket # try authorizing again, assuming the user has authed now
+      begin
+        cache_info(nil) # reset existing info
+        info = @api.get_account_info['user']
+        cache_info(info)
+      rescue Api::NotAuthorized, Api::InvalidInput
+        nil
       end
+    end
-      authorized?
+    # Get the root folder of the account. You can use this {Folder} object
+    # to access all sub items within the account. This folder is lazy loaded,
+    # and a network request will be made if/when the data is requested.
+    #
+    # @return [Folder] A folder object representing the root folder.
+    #
+    def root
+      return @root if @root
+      @root = Box::Folder.new(@api, nil, :id => 0)
+    end
+    # @return [Boolean] Is the account authorized?
+    def authorized?
+      @info != nil
     end
-    # tickets are used to associate authentication attempts, so each user needs their own ticket
+    protected
+    # @return [Api] The api currently in use.
+    attr_reader :api
+    # Get the cached ticket or request a new one from the Box api.
+    # @return [String] The authorization ticket.
     def ticket
       @ticket ||= @api.get_ticket['ticket']
     end
-    # the user must visit this url to allow the application to access their account
+    # The url the user needs to visit in order to grant this application
+    # permission to use their account. This requires a ticket, which
+    # is either pulled from the cache or requested.
+    #
+    # @param [String] ticket Use the ticket for the url.
+    #         If no ticket is provided, one will be requested and cached.
+    # @return [String] the url used for authorizing this account.
+    #
     def authorize_url(ticket = self.ticket)
       "#{ api.base_url }/auth/#{ ticket }"
     end
-    # using the ticket, we get the auth_token providing the user has already allowed our application the privilege
-    def authorize_ticket(ticket = self.ticket) # note: self.ticket will request a ticket if none exists, not the same as @ticket
+    # Attempt to authorize this account using the given ticket. This will
+    # only succeed if the user has granted this ticket permission, done
+    # by visiting and logging into the {#authorize_url}.
+    #
+    # @param [String] ticket The ticket used for authorization.
+    #         If no ticket is provided, one will be requested and cached.
+    # @return [String, nil] The auth token if successful otherwise, nil.
+    #
+    def authorize_ticket(ticket = self.ticket)
       begin
         response = @api.get_auth_token(ticket)
-        cache_info(response['user']) # cache account_info, saves an extra API call
-        authorize_token(response['auth_token'])
+        cache_info(response['user']) # saves an extra API call
+        cache_token(response['auth_token'])
       rescue Api::NotAuthorized
-        false
+        nil
       end
     end
-    # we have a token, and we have to save it and check if it is valid
-    def authorize_token(auth_token = self.auth_token)
-      @api.set_auth_token(auth_token)
-      @auth_token = auth_token if authorized? # set auth token if successful
-    end
-    # we are authorized if we have the user's account info
-    def authorized?
-      info != nil
-    end
-    # return the cached account info, or request it
-    def info
-      return @info if @info
+    # Attempt to authorize this account using the given auth token. This
+    # will only succeed if the auth token has been used before, and
+    # be done to make login easier.
+    #
+    # @param [String] auth_token The auth token to attempt to use
+    # @return [Boolean] If the attempt was successful.
+    #
+    def authorize_token(auth_token)
+      cache_token(auth_token)
+      info(true) # force a refresh
-      begin
-        info = @api.get_account_info['user']
-        cache_info(info)
-      rescue Api::NotAuthorized, Api::InvalidInput
-        nil
-      end
+      authorized?
     end
-    # return the root of the user's folder structure
-    def root
-      return @root if @root
-      @root = Box::Folder.new(@api, nil, :id => 0)
+    # Use and cache the given auth token.
+    # @param [String] auth_token The auth token to cache.
+    # @return [String] The auth token.
+    def cache_token(auth_token)
+      @api.set_auth_token(auth_token)
+      @auth_token = auth_token
     end
-    protected
-    # cache account info, possibly from get_auth_token, register_new_user, or get_account_info
+    # Cache the account info.
+    # @param [Hash] info The account info to cache.
     def cache_info(info)
       @info = info
     end

data/lib/box/api.rb CHANGED

@@ -3,11 +3,36 @@ require 'box/api/exceptions'
 require 'httmultiparty'
 module Box
-  class Api
-    include HTTMultiParty # a slight modification to HTTParty, adding multi-part upload support
-    attr_accessor :base_url, :upload_url
+  # A wrapper and interface to the Box api. Please visit the Box developers
+  # site for a full explaination of what each of the Box api methods
+  # expect and perform.
+  # TODO: Link to the site.
+  class Api
+    # an extension of HTTParty, adding multi-part upload support
+    include HTTMultiParty
+    # @return [String] The base url of the box api.
+    attr_accessor :base_url
+    # @return [String] The upload url of the box api.
+    attr_accessor :upload_url
+    # Create a new API object using the given parameters.
+    #
+    # @note Chances are that if the Box api is updated or moves location,
+    #       this class will no longer work. However, the option to change
+    #       the defaults still remains.
+    #
+    # @param [String, Api] api_key The api key for your application. You can
+    #        request one on the Box developer website at
+    #        {http://www.box.net/developers/services}. If an {Api} instance
+    #        is passed instead, its key is used.
+    #
+    # @param [String] url the url of the Box api.
+    # @param [String] upload_url the url of the upload host for the Box api.
+    # @param [String] version the version of the Box api in use.
+    #
     def initialize(key, url = 'https://box.net', upload_url = 'https://upload.box.net', version = '1.0')
       @default_params = { :api_key => key } # add the api_key to every query
@@ -15,20 +40,61 @@ module Box
       @upload_url = "#{ upload_url }/api/#{ version }" # uploads use a different url than everything else
     end
+    # Make a normal REST request.
+    #
+    # @param [String] expected the normal status expected to be returned.
+    #        If the actual status does not match, an exception is thrown.
+    # @param [Hash] options The parameters that wish to be passed in the
+    #        request. These should coorespond to the api specifications,
+    #        and will be passed along with the api key and auth token.
+    #
+    # @return [Hash] A parsed version of the XML response.
+    #
     def query_rest(expected, options = {})
       query_raw('get', "#{ @base_url }/rest", expected, options)['response']
     end
-    def query_download(query, args, options = {})
-      url = [ "#{ @base_url }/#{ query }", @auth_token, args ].flatten.compact.join('/') # /download/<auth_token>/<arg1>/<arg2>/<etc>
-      query_raw('get', url, nil, options) # note, expected is nil because the return will be raw data
+    # Make a download request.
+    #
+    # @param [String] query the operation to be performed ("download").
+    # @param [Array] args an array of arguments to put in the url.
+    # @param [Hash] options (see #query_rest)
+    #
+    # @return The raw binary data of the file.
+    #
+    def query_download(args, options = {})
+      # produces: /download/<auth_token>/<arg1>/<arg2>/<etc>
+      url = [ "#{ @base_url }/download", @auth_token, args ].flatten.compact.join('/')
+      query_raw('get', url, nil, options)
     end
+    # Make an upload request.
+    #
+    # @param [String] query The operation to be performed.
+    # @param [Array] args (see #query_download)
+    # @param [String] expected (see #query_rest)
+    # @param [Hash] options (see #query_rest)
+    #
+    # @return (see #query_rest)
+    #
     def query_upload(query, args, expected, options = {})
-      url = [ "#{ @upload_url }/#{ query }", @auth_token, args ].flatten.compact.join('/') # /upload/<auth_token>/<arg1>/<arg2>/<etc>
+      # produces: /upload/<auth_token>/<arg1>/<arg2>/<etc>
+      url = [ "#{ @upload_url }/#{ query }", @auth_token, args ].flatten.compact.join('/')
       query_raw('post', url, expected, options)['response']
     end
+    # Make a raw request.
+    #
+    # @note: HTTParty will automatically parse the response from its native
+    #        XML to a nested hash/array structure.
+    #
+    # @param ['get', 'post'] method The HTTP method to use.
+    # @param [String] url The url to make the request.
+    # @param [String] expected (see #query_rest)
+    # @param [Hash] options (see #query_rest)
+    #
+    # @return (see #query_rest)
+    #
     def query_raw(method, url, expected, options = {})
       response = case method
       when 'get'
@@ -40,6 +106,15 @@ module Box
       handle_response(response, expected)
     end
+    # Handle the response of the request.
+    #
+    # @param [Hash] response The parsed representation of the XML response.
+    # @param expected (see #query_rest)
+    #
+    # @return [Hash] The response if no errors were found.
+    # @raise [Exception, UnknownResponse] Raises an exception if the
+    #        response status does not match the expected. This exception
+    #        is determined by {.get_exception}
     def handle_response(response, expected = nil)
       if expected
         begin
@@ -58,83 +133,166 @@ module Box
       response
     end
+    # TODO: Add link to API documentation for all functions below.
+    # TODO: Document exceptions that could be thrown.
+    # Request a ticket for authorization
     def get_ticket
       query_rest('get_ticket_ok', :action => :get_ticket)
     end
+    # Request an auth token given a ticket.
+    #
+    # @param [String] ticket the ticket to use.
     def get_auth_token(ticket)
       query_rest('get_auth_token_ok', :action => :get_auth_token, :ticket => ticket)
     end
-    # save the auth token and add it to every request
+    # Add the auth token to every request.
+    #
+    # @param [String] auth_token The auth token to add to every request.
     def set_auth_token(auth_token)
       @auth_token = auth_token
       @default_params[:auth_token] = auth_token
     end
+    # Request the user be logged out.
     def logout
       query_rest('logout_ok', :action => :logout)
     end
-    def register_new_user(login, password)
-      query_rest('successful_register', :action => :register_new_user, :login => login, :password => password)
+    # Register a new user.
+    #
+    # @param [String] email The email address to use.
+    # @param [String] password The password to use.
+    def register_new_user(email, password)
+      query_rest('successful_register', :action => :register_new_user, :login => email, :password => password)
     end
-    def verify_registration_email(login)
-      query_rest('email_ok', :action => :verify_registration_email, :login => login)
+    # Verify a registration email.
+    #
+    # @param [String] email The email address to check.
+    def verify_registration_email(email)
+      query_rest('email_ok', :action => :verify_registration_email, :login => email)
     end
+    # Get the user's account info.
     def get_account_info
       query_rest('get_account_info_ok', :action => :get_account_info)
     end
-    # TODO: Use zip compression to save space
-    def get_account_tree(folder_id = 0, *args)
+    # Get the entire tree of a given folder.
+    #
+    # @param [String] folder_id The id of the folder to use.
+    # @param [Array] args The arguments to pass along to get_account_tree.
+    #
+    # @note This function can take a long time for large folders.
+    # @todo Use zip compression to save bandwidth.
+    #
+    # TODO: document the possible arguments.
+    def get_account_tree(folder_id, *args)
       query_rest('listing_ok', :action => :get_account_tree, :folder_id => folder_id, :params => [ 'nozip' ] + args)
     end
+    # Create a new folder.
+    #
+    # @param [String] parent_id The id of the parent folder to use.
+    # @param [String] name The name of the newly created folder.
+    # @param [Integer] shared The shared state of the new folder.
     def create_folder(parent_id, name, share = 0)
       query_rest('create_ok', :action => :create_folder, :parent_id => parent_id, :name => name, :share => share)
     end
+    # Move the item to a new destination.
+    #
+    # @param ["file", "folder"] target The type of item.
+    # @param [String] target_id The id of the item to move.
+    # @param [String] destination_id The id of the parent to move to.
     def move(target, target_id, destination_id)
       query_rest('s_move_node', :action => :move, :target => target, :target_id => target_id, :destination_id => destination_id)
     end
+    # Copy the the item to a new destination.
+    #
+    # @note The api currently only supports copying files.
+    #
+    # @param ["file"] target The type of item.
+    # @param [String] target_id The id of the item to copy.
+    # @param [String] destination_id The id of the parent to copy to.
     def copy(target, target_id, destination_id)
       query_rest('s_copy_node', :action => :copy, :target => target, :target_id => target_id, :destination_id => destination_id)
     end
+    # Rename the item.
+    #
+    # @param ["file", "folder"] target The type of item.
+    # @param [String] target_id The id of the item to rename.
+    # @param [String] new_name The new name to be used.
     def rename(target, target_id, new_name)
       query_rest('s_rename_node', :action => :rename, :target => target, :target_id => target_id, :new_name => new_name)
     end
+    # Delete the item.
+    #
+    # @param ["file", "folder"] target The type of item.
+    # @param [String] target_id The id of the item to delete.
     def delete(target, target_id)
       query_rest('s_delete_node', :action => :delete, :target => target, :target_id => target_id)
     end
+    # Get the file info.
+    #
+    # @param [String] file_id The file id to get info for.
     def get_file_info(file_id)
       query_rest('s_get_file_info', :action => :get_file_info, :file_id => file_id)
     end
+    # Set the item description.
+    #
+    # @param ["file", "folder"] target The type of item.
+    # @param [String] target_id The id of the item to describe.
+    # @param [String] description The description to use.
     def set_description(target, target_id, description)
       query_rest('s_set_description', :action => :set_description, :target => target, :target_id => target_id, :description => description)
     end
+    # Download the file to the given path.
+    #
+    # @note You cannot download folders.
+    #
+    # @param [String] path The path to write the file to.
+    # @param [String] file_id The file id to download.
+    # @param [Optional, String] version The version of the file to download.
     def download(path, file_id, version = nil)
       ::File.open(path, 'w') do |file|
-        file << query_download('download', [ file_id, version ]) # write the response directly to file
+        file << query_download([ file_id, version ]) # write the response directly to file
       end
     end
+    # Upload the file to the specified folder.
+    #
+    # @param [String] path Upload the file at the given path.
+    # @param [String] folder_id The folder id of the parent folder to use.
+    # @param [Optional, Boolean] new_copy Upload a new copy instead of overwriting.
     def upload(path, folder_id, new_copy = false)
       query_upload('upload', folder_id, 'upload_ok', :file => ::File.new(path), :new_copy => new_copy)
     end
+    # Overwrite the given file with a new one.
+    #
+    # @param [String] path (see #upload)
+    # @param [String] file_id Replace the file with this id.
+    # @param [Optional, String] name Use a new name as well.
     def overwrite(path, file_id, name = nil)
       query_upload('overwrite', file_id, 'upload_ok', :file => ::File.new(path), :file_name => name)
     end
+    # Upload a new copy of the given file.
+    #
+    # @param [String] path (see #upload)
+    # @param [String] file_id The id of the file to copy.
+    # @param [Optional, String] name Use a new name as well.
+    # TODO: Verfiy this does what I think it does
     def new_copy(path, file_id, name = nil)
       query_upload('new_copy', file_id, 'upload_ok', :file => ::File.new(path), :new_file_name => name)
     end