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

box-api 0.1.7 → 0.1.8

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

@@ -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