1 files changed, 17 insertions, 26 deletions

diff --git a/lib/mogilefs/backend.rb b/lib/mogilefs/backend.rb
index dd775ca..518e67e 100644
--- a/lib/mogilefs/backend.rb
+++ b/lib/mogilefs/backend.rb
@@ -1,14 +1,12 @@
 # -*- encoding: binary -*-
 require 'thread'
 
-##
-# MogileFS::Backend communicates with the MogileFS trackers.
-
+# This class communicates with the MogileFS trackers.
+# You should not have to use this directly unless you are developing
+# support for new commands or plugins for MogileFS
 class MogileFS::Backend
 
-  ##
   # Adds MogileFS commands +names+.
-
   def self.add_command(*names)
     names.each do |name|
       define_method name do |*args|
@@ -17,6 +15,8 @@ class MogileFS::Backend
     end
   end
 
+  # adds idempotent MogileFS commands +names+, these commands may be retried
+  # transparently on a different tracker if there is a network/server error.
   def self.add_idempotent_command(*names)
     names.each do |name|
       define_method name do |*args|
@@ -25,7 +25,7 @@ class MogileFS::Backend
     end
   end
 
-  BACKEND_ERRORS = {}
+  BACKEND_ERRORS = {} # :nodoc:
 
   # this converts an error code from a mogilefsd tracker to an exception:
   #
@@ -160,9 +160,7 @@ class MogileFS::Backend
     end
   end
 
-  ##
   # Performs the +cmd+ request with +args+.
-
   def do_request(cmd, args, idempotent = false)
     request = make_request cmd, args
     @mutex.synchronize do
@@ -199,9 +197,7 @@ class MogileFS::Backend
     end # @mutex.synchronize
   end
 
-  ##
   # Makes a new request string for +cmd+ and +args+.
-
   def make_request(cmd, args)
     "#{cmd} #{url_encode args}\r\n"
   end
@@ -214,10 +210,8 @@ class MogileFS::Backend
     BACKEND_ERRORS[err_snake] || self.class.add_error(err_snake)
   end
 
-  ##
   # Turns the +line+ response from the server into a Hash of options, an
   # error, or raises, as appropriate.
-
   def parse_response(line)
     if line =~ /^ERR\s+(\w+)\s*([^\r\n]*)/
       @lasterr = $1
@@ -231,9 +225,7 @@ class MogileFS::Backend
           "Invalid response from server: #{line.inspect}"
   end
 
-  ##
   # Returns a socket connected to a MogileFS tracker.
-
   def socket
     return @socket if @socket and not @socket.closed?
 
@@ -259,40 +251,39 @@ class MogileFS::Backend
           "couldn't connect to any tracker: #{errors.join(', ')}"
   end
 
-  ##
   # Turns a url params string into a Hash.
-
-  def url_decode(str)
+  def url_decode(str) # :nodoc:
     Hash[*(str.split(/&/).map! { |pair|
       pair.split(/=/, 2).map! { |x| url_unescape(x) }
     } ).flatten]
   end
 
-  ##
-  # Turns a Hash (or Array of pairs) into a url params string.
+  # :stopdoc:
+  # TODO: see if we can use existing URL-escape/unescaping routines
+  # in the Ruby standard library, Perl MogileFS seems to NIH these
+  #  routines, too
+  # :startdoc:
 
-  def url_encode(params)
+  # Turns a Hash (or Array of pairs) into a url params string.
+  def url_encode(params) # :nodoc:
     params.map do |k,v|
       "#{url_escape k.to_s}=#{url_escape v.to_s}"
     end.join("&")
   end
 
-  ##
   # Escapes naughty URL characters.
   if ''.respond_to?(:ord) # Ruby 1.9
-    def url_escape(str)
+    def url_escape(str) # :nodoc:
       str.gsub(/([^\w\,\-.\/\\\: ])/) { "%%%02x" % $1.ord }.tr(' ', '+')
     end
   else # Ruby 1.8
-    def url_escape(str)
+    def url_escape(str) # :nodoc:
       str.gsub(/([^\w\,\-.\/\\\: ])/) { "%%%02x" % $1[0] }.tr(' ', '+')
     end
   end
 
-  ##
   # Unescapes naughty URL characters.
-
-  def url_unescape(str)
+  def url_unescape(str) # :nodoc:
     str.gsub(/%([a-f0-9][a-f0-9])/i) { [$1.to_i(16)].pack 'C' }.tr('+', ' ')
   end
 end