1 files changed, 38 insertions, 1 deletions
diff --git a/lib/webrick/httpauth/htdigest.rb b/lib/webrick/httpauth/htdigest.rb
index 3949756f2b..4b74588c77 100644
--- a/lib/webrick/httpauth/htdigest.rb
+++ b/lib/webrick/httpauth/htdigest.rb
@@ -13,9 +13,26 @@ require 'tempfile'
 
 module WEBrick
   module HTTPAuth
+
+    ##
+    # Htdigest accesses apache-compatible digest password files.  Passwords are
+    # matched to a realm where they are valid.  For security, the path for a
+    # digest password database should be stored outside of the paths available
+    # to the HTTP server.
+    #
+    # Htdigest is intended for use with WEBrick::HTTPAuth::DigestAuth and
+    # stores passwords using cryptographic hashes.
+    #
+    #   htpasswd = WEBrick::HTTPAuth::Htdigest.new 'my_password_file'
+    #   htpasswd.set_passwd 'my realm', 'username', 'password'
+    #   htpasswd.flush
+
     class Htdigest
       include UserDB
 
+      ##
+      # Open a digest password database at +path+
+
       def initialize(path)
         @path = path
         @mtime = Time.at(0)
@@ -26,6 +43,9 @@ module WEBrick
         reload
       end
 
+      ##
+      # Reloads passwords from the database
+
       def reload
         mtime = File::mtime(@path)
         if mtime > @mtime
@@ -44,6 +64,10 @@ module WEBrick
         end
       end
 
+      ##
+      # Flush the password database.  If +output+ is given the database will
+      # be written there instead of to the original path.
+
       def flush(output=nil)
         output ||= @path
         tmp = Tempfile.new("htpasswd", File::dirname(output))
@@ -56,6 +80,10 @@ module WEBrick
         end
       end
 
+      ##
+      # Retrieves a password from the database for +user+ in +realm+.  If
+      # +reload_db+ is true the database will be reloaded first.
+
       def get_passwd(realm, user, reload_db)
         reload() if reload_db
         if hash = @digest[realm]
@@ -63,6 +91,9 @@ module WEBrick
         end
       end
 
+      ##
+      # Sets a password in the database for +user+ in +realm+ to +pass+.
+
       def set_passwd(realm, user, pass)
         @mutex.synchronize{
           unless @digest[realm]
@@ -72,13 +103,19 @@ module WEBrick
         }
       end
 
+      ##
+      # Removes a password from the database for +user+ in +realm+.
+
       def delete_passwd(realm, user)
         if hash = @digest[realm]
           hash.delete(user)
         end
       end
 
-      def each
+      ##
+      # Iterate passwords in the database.
+
+      def each # :yields: [user, realm, password_hash]
         @digest.keys.sort.each{|realm|
           hash = @digest[realm]
           hash.keys.sort.each{|user|