lib/defog/handle.rb in defog-0.3.0 vs lib/defog/handle.rb in defog-0.3.1

@@ -76,23 +76,30 @@
       @proxy.fog_wrapper.fog_head(@key)
     end
 
     # Returns a Defog::File object, which is a specialization of ::File. 
     #
-    # <code>mode</code> can be "r", "r+", "w", "w+", "a", or "a+" with the
+    # <code>mode</code> can be the usual "r", "r+", "w", "w+", "a", or "a+" with the
     # usual semantics.  When opened in a readable mode ("r", "r+", "w+",
     # "a+"), first caches the cloud file in the local proxy.  When opened
     # in a writeable mode ("r+", "w", "w+", "a", "a+"), arranges to upload
-    # the changes back to the cloud file at close time.
+    # the changes back to the cloud file at close time.  The mode can be
+    # suffixed with 'b' or with ':' and encoding specifiers as usual.
     #
     # Like ::File.open, if called with a block yields the file object to
     # the block and ensures the file will be closed when leaving the block.
     #
     # Normally upon close the proxy file is synchronized as needed and then deleted.
     # Pass
     #    :persist => true
     # to suppress deleting the file and so maintain the file after closing.   See File#close for more
     # details.
+    #
+    # If you are managing your cache size, when opening a proxy for writing
+    # you may want to provide a hint as to the expected size of the data:
+    #    :size_hint => 500.kilobytes
+    # See README for more details.
+    #
     def open(mode, opts={}, &block)
       opts = opts.keyword_args(:persist => @proxy.persist, :size_hint => :optional)
       File.open(opts.merge(:handle => self, :mode => mode), &block)
     end