new_file: documentation for :content_md5 usage

Now that checksum support is officially a part of MogileFS, we
can document (and thus encourage) it without risking
compatibility issues.

1 files changed, 14 insertions, 0 deletions

diff --git a/lib/mogilefs/mogilefs.rb b/lib/mogilefs/mogilefs.rb
index 9f4f988..f206810 100644
--- a/lib/mogilefs/mogilefs.rb
+++ b/lib/mogilefs/mogilefs.rb
@@ -172,6 +172,20 @@ class MogileFS::MogileFS < MogileFS::Client
   # [ :class => String]
   #
   #   The MogileFS storage class of the object.
+  #
+  # [:content_md5 => String, Proc, or :trailer]
+  #
+  #   This can either be a Base64-encoded String, a Proc object, or
+  #   the :trailer symbol.  If given a String, it will be used as the
+  #   Content-MD5 HTTP header.  If given the :trailer symbol, this library
+  #   will automatically generate an Content-MD5 HTTP trailer.  If given
+  #   a Proc object, this Proc object should give a Base64-encoded string
+  #   which can be used as the Content-MD5 HTTP trailer when called at the
+  #   end of the request.
+  #
+  #   Keep in mind most HTTP servers do not support HTTP trailers, so
+  #   passing a String is usually the safest way to use this.
+  #
   def new_file(key, args = nil, bytes = nil) # :yields: file
     raise MogileFS::ReadOnlyError if readonly?
     opts = { :key => key, :multi_dest => 1 }