misc. documentation improvements

100% RDoc coverage (not that it's an indicator of _good_
documentation, but we're getting there)

5 files changed, 13 insertions, 11 deletions

diff --git a/lib/mogilefs.rb b/lib/mogilefs.rb
index ba6ca95..130b13b 100644
--- a/lib/mogilefs.rb
+++ b/lib/mogilefs.rb
@@ -21,7 +21,9 @@ module MogileFS
 
   # Raised when a backend is in read-only mode
   class ReadOnlyError < Error
-    def message; 'readonly mogilefs'; end
+    def message # :nodoc:
+      'readonly mogilefs'
+    end
   end
 
   # Raised when an upload is impossible
diff --git a/lib/mogilefs/admin.rb b/lib/mogilefs/admin.rb
index d79a280..0927e47 100644
--- a/lib/mogilefs/admin.rb
+++ b/lib/mogilefs/admin.rb
@@ -273,6 +273,7 @@ class MogileFS::Admin < MogileFS::Client
     rv
   end
 
+  # Clears the tracker caches.  Not implemented in all versions of MogileFS
   def clear_cache
     @backend.clear_cache
   end
diff --git a/lib/mogilefs/backend.rb b/lib/mogilefs/backend.rb
index e546350..d04247b 100644
--- a/lib/mogilefs/backend.rb
+++ b/lib/mogilefs/backend.rb
@@ -42,7 +42,7 @@ class MogileFS::Backend
     BACKEND_ERRORS[err_snake] = const_get(err_camel)
   end
 
-  def self.const_missing(name)
+  def self.const_missing(name) # :nodoc:
     if /Error\z/ =~ name.to_s
       const_set(name, Class.new(MogileFS::Error))
     else
diff --git a/lib/mogilefs/client.rb b/lib/mogilefs/client.rb
index 9a2f34b..696f31f 100644
--- a/lib/mogilefs/client.rb
+++ b/lib/mogilefs/client.rb
@@ -11,7 +11,9 @@ class MogileFS::Client
 
   attr_reader :backend
 
+  # :stopdoc:
   attr_accessor :hosts if defined? $TESTING
+  # :startdoc
 
   ##
   # Creates a new Client.  See MogileFS::Backend#initialize for how to specify
diff --git a/lib/mogilefs/new_file.rb b/lib/mogilefs/new_file.rb
index baac6e2..d7ade5b 100644
--- a/lib/mogilefs/new_file.rb
+++ b/lib/mogilefs/new_file.rb
@@ -7,8 +7,8 @@
 # of awkward APIs.
 #
 # It is possible to stream large content of known length any WebDAV server.
-# One example of this is for mirroring a file from an existing HTTP server without download downloading
-
+# One example of this is for mirroring a large file from an existing HTTP
+# server to \MogileFS without letting it hit the local filesystem.
 #
 #   uri = URI('http://example.com/large_file')
 #   Net::HTTP.start(uri.host, uri.port) do |http|
@@ -20,16 +20,12 @@
 #       else
 #         warn "trying to upload with Transfer-Encoding: chunked"
 #         warn "this is not supported by all WebDAV servers"
-#         io = mg.new_file('key', :largefile => :chunked)
+#         io = mg.new_file('key', :largefile => :stream)
 #       end
 #       response.read_body { |buf| io.write(buf) }
 #       io.close
 #     end
 #   end
-
-#   nf = mg.new_file("key", :largefile => stream, :content_length => )
-#   nf.write(buf)
-#   nf.close
 #
 # If your WebDAV servers have chunked PUT support (e.g. Perlbal), you can
 # stream a file of unknown length using "Transfer-Encoding: chunked".
@@ -49,11 +45,12 @@
 #   nf.close
 #
 # Finally, if your WebDAV servers does not support either partial nor
-# nor chunked PUTs, you must buffer a file of unknown length using a
-# Tempfile:
+# nor chunked PUTs, you must buffer a large file of unknown length
+# using a Tempfile:
 #
 #   nf = mg.new_file("key", :largefile => :tempfile)
 #   nf.write "hello"
+#   nf.write ...
 #   nf.close
 #
 module MogileFS::NewFile