* lib/webrick: Add documentation for WEBrick::HTTPAuth

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31505 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 39 insertions, 1 deletions

diff --git a/lib/webrick/httpauth/htpasswd.rb b/lib/webrick/httpauth/htpasswd.rb
index 8a058861d3..205a6db2f0 100644
--- a/lib/webrick/httpauth/htpasswd.rb
+++ b/lib/webrick/httpauth/htpasswd.rb
@@ -13,9 +13,27 @@ require 'tempfile'
 
 module WEBrick
   module HTTPAuth
+
+    ##
+    # Htpasswd accesses apache-compatible password files.  Passwords are
+    # matched to a realm where they are valid.  For security, the path for a
+    # password database should be stored outside of the paths available to the
+    # HTTP server.
+    #
+    # Htpasswd is intended for use with WEBrick::HTTPAuth::BasicAuth.
+    #
+    # To create an Htpasswd database with a single user:
+    #
+    #   htpasswd = WEBrick::HTTPAuth::Htpasswd.new 'my_password_file'
+    #   htpasswd.set_passwd 'my realm', 'username', 'password'
+    #   htpasswd.flush
+
     class Htpasswd
       include UserDB
 
+      ##
+      # Open a password database at +path+
+
       def initialize(path)
         @path = path
         @mtime = Time.at(0)
@@ -25,6 +43,9 @@ module WEBrick
         reload
       end
 
+      ##
+      # Reload passwords from the database
+
       def reload
         mtime = File::mtime(@path)
         if mtime > @mtime
@@ -48,6 +69,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))
@@ -60,20 +85,33 @@ 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
         @passwd[user]
       end
 
+      ##
+      # Sets a password in the database for +user+ in +realm+ to +pass+.
+
       def set_passwd(realm, user, pass)
         @passwd[user] = make_passwd(realm, user, pass)
       end
 
+      ##
+      # Removes a password from the database for +user+ in +realm+.
+
       def delete_passwd(realm, user)
         @passwd.delete(user)
       end
 
-      def each
+      ##
+      # Iterate passwords in the database.
+
+      def each # :yields: [user, password]
         @passwd.keys.sort.each{|user|
           yield([user, @passwd[user]])
         }