box-api 0.1.7 → 0.1.8

data/lib/box/api/exceptions.rb

@@ -29,6 +29,10 @@ module Box
     class AccountExceeded < Exception; end
     class SizeExceeded < Exception; end
 
+    # Given a status, returning a cooresponding Exception class.
+    #
+    # @param [String] status The failing status to look for.
+    # @return [Exception] A coorespondng Exception.
     def self.get_exception(status)
       case status
       # Common responses

data/lib/box/file.rb

@@ -1,15 +1,24 @@
 require 'box/item'
 
 module Box
+  # Represents a file stored on Box. Any attributes or actions typical to
+  # a Box file can be accessed through this class.
+
   class File < Item
+    # (see Item.type)
     def self.type; 'file'; end
 
-    # download the file to the specified path
+    # Download this file to the specified path.
+    #
+    # @param [String] path The path to write the file.
     def download(path)
       @api.download(path, id)
     end
 
-    # overwrite this file, using the file at the specified path
+    # Overwrite this file, using the file at the specified path
+    #
+    # @param [String] path The path to the file to upload.
+    # @return [File] self
     def upload_overwrite(path)
       info = @api.overwrite(path, id)['files']['file']
 
@@ -19,7 +28,11 @@ module Box
       self
     end
 
-    # upload a new copy of this file, the name being 'file (#).ext' for the #th copy
+    # Upload a new copy of this file. The name will be "file (#).ext"
+    # for the each additional copy.
+    #
+    # @param path (see #upload_overwrite)
+    # @return [File] The newly created file.
     def upload_copy(path)
       info = @api.new_copy(path, id)['files']['file']
       parent.delete_info('files')
@@ -29,7 +42,7 @@ module Box
 
     protected
 
-    # get the file info
+    # (see Item#get_info)
     def get_info
       @api.get_file_info(id)['info']
     end

data/lib/box/folder.rb

@@ -2,12 +2,16 @@ require 'box/item'
 require 'box/file'
 
 module Box
-  class Folder < Item
-    attr_accessor :cached_tree
+  # Represents a folder stored on Box. Any attributes or actions typical to
+  # a Box folder can be accessed through this class.
 
+  class Folder < Item
+    # (see Item.type)
     def self.type; 'folder'; end
 
-    # override the existing info method so that we create empty folders/files first
+    # (see Item#info)
+    # Files and folders will only be one-level deep, and {#tree} should be
+    # used if fetching deeper than that.
     def info(refresh = false)
       return self if @cached_info and not refresh
 
@@ -17,7 +21,16 @@ module Box
       super
     end
 
-    # use the cached tree or update it if requested
+    # Get the tree for this folder. The tree includes all sub folders and
+    # files, including their info. Uses a cached copy if avaliable,
+    # or else it is fetched from the api.
+    #
+    # @note Fetching the tree can take a long time for large folders. There
+    #       is a trade-off between one {#tree} call and multiple {#info}
+    #       calls, so use the one most relevant for your application.
+    #
+    # @param [Boolean] refresh Does not use the cached copy if true.
+    # @return [Folder] self
     def tree(refresh = false)
       return self if @cached_tree and not refresh
 
@@ -30,7 +43,12 @@ module Box
       self
     end
 
-    # create a new folder using this folder as the parent
+    # Create a new folder using this folder as the parent.
+    #
+    # @param [String] name The name of the new folder.
+    # @param [Integer] share The shared status of the new folder. Defaults
+    #        to not being shared.
+    # @return [Folder] The new folder.
     def create(name, share = 0)
       info = @api.create_folder(id, name, share)['folder']
 
@@ -39,7 +57,10 @@ module Box
       Box::Folder.new(api, self, info)
     end
 
-    # upload a new file using this folder as the parent
+    # Upload a new file using this folder as the parent
+    #
+    # @param [String] path The path of the file on disk to upload.
+    # @return [File] The new file.
     def upload(path)
       info = @api.upload(path, id)['files']['file']
 
@@ -48,7 +69,29 @@ module Box
       Box::File.new(api, self, info)
     end
 
-    # search for items using criteria
+    # Search for sub-items using criteria.
+    #
+    # @param [Hash] criteria The hash of criteria to use. Each key of
+    #        the criteria will be called on each sub-item and tested
+    #        for equality. This lets you use any method of {Item}, {Folder},
+    #        and {File} as the criteria.
+    # @return [Array] An array of all sub-items that matched the criteria.
+    #
+    # @note The recursive option will call {#tree}, which can be slow for
+    #       large folders.
+    # @note Any item method (as a symbol) can be used as criteria, which
+    #       could cause major problems if used improperly.
+    #
+    # @example Find all sub-items with the name 'README'
+    #   folder.search(:name => 'README')
+    #
+    # @example Recusively find a sub-item with the given path.
+    #   folder.search(:path => '/test/file.mp4', :recursive => true)
+    #
+    # @example Recursively find all files with a given sha1.
+    #   folder.search(:type => 'file', :sha1 => 'abcdefg', :recursive => true)
+    #
+    # TODO: Lookup YARD syntax for options hash.
     def find(criteria)
       recursive = criteria.delete(:recursive)
       recursive = false if recursive == nil # default to false for performance reasons
@@ -58,24 +101,49 @@ module Box
       find!(criteria, recursive)
     end
 
+    # (see Item#force_cached_info)
+    def force_cached_info
+      create_sub_items(nil, Box::Folder)
+      create_sub_items(nil, Box::File)
+
+      super
+    end
+
+    # Consider the tree cached. This prevents an additional api
+    # when we know the item is fully fetched.
+    def force_cached_tree
+      @cached_tree = true
+
+      create_sub_items(nil, Box::Folder)
+      create_sub_items(nil, Box::File)
+
+      folders.each do |folder|
+        folder.force_cached_tree
+      end
+    end
+
     protected
 
-    # get the folder info
+    attr_accessor :cached_tree
+
+    # (see Item#get_info)
     def get_info
       @api.get_account_tree(id, 'onelevel')['tree']['folder']
     end
 
-    # get the folder info and all nested items
+    # Fetch the folder tree from the api.
+    # @return [Hash] The folder tree.
     def get_tree
-      @api.get_account_tree(id)['tree']['folder']
+      @api.get_account_tree(id, 'simple')['tree']['folder']
     end
 
+    # (see Item#clear_info)
     def clear_info
       @cached_tree = false
       super
     end
 
-    # overload Item#update_info to create the subobjects like Files and Folders
+    # (see Item#update_info)
     def update_info(info)
       if folders = info.delete('folders')
         create_sub_items(folders, Box::Folder)
@@ -88,7 +156,11 @@ module Box
       super
     end
 
-    # create the sub items, so they are objects rather than hashes
+    # Create objects for the sub items.
+    #
+    # @param [Array] items Array of item info.
+    # @param [Item] item_class The class of the items in the Array.
+    # @return [Array] Array of {Item}s.
     def create_sub_items(items, item_class)
       @data[item_class.types] ||= Array.new
 
@@ -104,24 +176,7 @@ module Box
       end
     end
 
-    # update the cached status of all sub items, as we got the entire tree
-    def force_cached_tree
-      create_sub_items(nil, Box::Folder)
-      create_sub_items(nil, Box::File)
-
-      files.each do |file|
-        file.cached_info = true
-      end
-
-      folders.each do |folder|
-        folder.cached_info = true
-        folder.cached_tree = true
-
-        folder.force_cached_tree
-      end
-    end
-
-    # search for any files/folders that match the criteria sent
+    # (see #find)
     def find!(criteria, recursive)
       matches = (files + folders).collect do |item| # search over our files and folders
         match = criteria.all? do |key, value| # make sure all criteria pass

data/lib/box/item.rb

@@ -1,8 +1,24 @@
 module Box
+  # Represents a folder or file stored on Box. Any attributes or actions
+  # typical to a Box item can be accessed through this class. The {Item}
+  # class contains only methods shared by {Folder} and {File}, and should
+  # not be instanciated directly.
+
   class Item
-    attr_accessor :data, :api, :parent
-    attr_accessor :cached_info
+    # @return [Hash] The hash of info for this item.
+    attr_accessor :data
+
+    # @return [Api] The {Api} used by this item.
+    attr_accessor :api
+
+    # @return [Folder] The parent of this item.
+    attr_accessor :parent
 
+    # Create a new item representing either a file or folder.
+    #
+    # @param [Api] api The {Api} instance used to generate requests.
+    # @param [Folder] parent The {Folder} parent of this item.
+    # @param [Hash] info The hash of initial info for this item.
     def initialize(api, parent, info)
       @api = api
       @parent = parent
@@ -11,17 +27,31 @@ module Box
       update_info(info) # merges with the info hash, and renames some fields
     end
 
-    # return the string representation of this item (file or folder)
+    # @return [String] The string representation of this item.
     def self.type; raise "Overwrite this method"; end
+
+    # @return [String] The plural string representation of this item.
     def self.types; type + 's'; end
 
-    # should be a better way of doing this
+    # TODO: There should be a better way of doing this.
+
+    # (see .type)
     def type; self.class.type; end
+
+    # (see .types)
     def types; self.class.types; end
 
-    def id; @data['id']; end # overwrite Object#id, which is not what we want
+    # @return [String] The id of this item.
+    def id
+      # overloads Object#id
+      @data['id']
+    end
 
-    # use cached info or update it if requested
+    # Get the info for this item. Uses a cached copy if avaliable,
+    # or else it is fetched from the api.
+    #
+    # @param [Boolean] refresh Does not use the cached copy if true.
+    # @return [Item] self
     def info(refresh = false)
       return self if @cached_info and not refresh
 
@@ -31,7 +61,10 @@ module Box
       self
     end
 
-    # move the item to the destination folder
+    # Move this item to the destination folder.
+    #
+    # @param [Folder] destination The new parent folder to use.
+    # @return [Item] self
     def move(destination)
       @api.move(type, id, destination.id)
 
@@ -43,7 +76,12 @@ module Box
       self
     end
 
-    # copy the file (folder not supported in the api) to the destination folder
+    # Copy this item to the destination folder.
+    #
+    # @note Copying folders is not currently supported.
+    #
+    # @param [Folder] destination The parent folder to copy the item to.
+    # @return [Item] The new copy of this item.
     def copy(destination)
       @api.copy(type, id, destination.id)
 
@@ -52,7 +90,10 @@ module Box
       self.class.new(api, destination, @data)
     end
 
-    # rename the item
+    # Rename this item.
+    #
+    # @param [String] new_name The new name for the item.
+    # @return [Item] self
     def rename(new_name)
       @api.rename(type, id, new_name)
 
@@ -61,7 +102,10 @@ module Box
       self
     end
 
-    # delete the item
+    # Delete this item and all sub-items.
+    #
+    # @return [Item] self
+    # TODO: Return nil instead
     def delete
       @api.delete(type, id)
 
@@ -71,41 +115,62 @@ module Box
       self
     end
 
-    # set the description of the item
+    # Set the description of this item.
+    #
+    # @param [String] message The description message to use.
+    # @return [Item] self
     def description(message)
       @api.set_description(type, id, message)
 
       self
     end
 
-    # get the path, starting with /
+    # @return [String] The path of this item. This starts with a '/'.
     def path
       "#{ parent.path + '/' if parent }#{ name }"
     end
 
-    # use method_missing as to provide an easy way to access the item's properties
+    # Provides an easy way to access this item's info.
+    #
+    # @example
+    #   item.name # returns @data['name'] or fetches it if not cached
     def method_missing(sym, *args, &block)
+      # TODO: Why not symbols?
+      # convert to a string
       str = sym.to_s
 
       # return the value if it already exists
       return @data[str] if @data.key?(str)
 
-      # value didn't exist, so update the info
+      # value didn't exist, so try to update the info
       self.info
 
-      # try again
+      # try returning the value again
       return @data[str] if @data.key?(str)
 
       # we didn't find a value, so it must be invalid
+      # call the normal method_missing function
       super
     end
 
+    # Consider the item cached. This prevents an additional api
+    # when we know the item is fully fetched.
+    def force_cached_info
+      @cached_info = true
+    end
+
     protected
 
-    # sub-classes are meant to implement this
-    def get_info(*args); Hash.new; end
+    # Fetches this item's info from the api.
+    #
+    # @return [Hash] The info for the item.
+    def get_info; Hash.new; end
 
-    # takes in a hash of info, cleans it, and merges it into the existing info
+    # Merges in the given info, making sure the fields are uniform.
+    # This is done because the api will occasionally return fields like
+    # 'file_id', but we want just 'id'.
+    #
+    # @param [Hash] info A hash to be merged this item's info
     def update_info(info)
       ninfo = Hash.new
 
@@ -118,13 +183,17 @@ module Box
       @data.merge!(ninfo) # merge in the updated info
     end
 
-    # delete the cache for a specific info
+    # Invalidates and deletes the cache for a specific field. This forces
+    # the item to lazy-load this field if it is requested.
+    #
+    # @param [String] field The field to delete.
     def delete_info(field)
       @cached_info = false
       @data.delete(field)
     end
 
-    # delete the entire cache
+    # Invalidates and deletes the entire cache. This forces all info to be
+    # lazy-loaded if requested.
     def clear_info
       @cached_info = false
       @data.clear

data/spec/account_spec.rb

@@ -9,10 +9,6 @@ describe Box::Account do
       @account = get_account(false)
     end
 
-    it "gets a ticket" do
-      @account.ticket.should_not == nil
-    end
-
     it "fails to authorize without auth token" do
       @account.authorize.should == false
     end