M README.md → README.md

@@ -6,6 +6,45 @@
 Package captcha implements generation and verification of image and audio
 CAPTCHAs.
 
+A captcha solution is the sequence of digits 0-9 with the defined length.
+There are two captcha representations: image and audio.
+
+An image representation is a PNG-encoded image with the solution printed on
+it in such a way that makes it hard for computers to solve it using OCR.
+
+An audio representation is a WAVE-encoded (8 kHz unsigned 8-bit) sound
+with the spoken solution (currently in English). To make it hard for
+computers to solve audio captcha, the voice that pronounces numbers has
+random speed and pitch, and there is a randomly generated background noise
+mixed into the sound.
+
+This package doesn't require external files or libraries to generate captcha
+representations; it is self-contained.
+
+To make captchas one-time, the package includes a memory storage that stores
+captcha ids, their solutions, and expiration time. Used captchas are removed
+from the store immediately after calling Verify or VerifyString, while
+unused captchas (user loaded a page with captcha, but didn't submit the
+form) are collected automatically after the predefined expiration time.
+Developers can also provide custom store (for example, which saves captcha
+ids and solutions in database) by implementing Store interface and
+registering the object with SetCustomStore.
+
+Captchas are created by calling New, which returns the captcha id.  Their
+representations, though, are created on-the-fly by calling WriteImage or
+WriteAudio functions. Created representations are not stored anywhere, so
+subsequent calls to these functions with the same id will write the same
+captcha solution, but with a different random representation. Reload
+function will create a new different solution for the provided captcha,
+allowing users to "reload" captcha if they can't solve the displayed one
+without reloading the whole page.  Verify and VerifyString are used to
+verify that the given solution is the right one for the given captcha id.
+
+Server provides an http.Handler which can serve image and audio
+representations of captchas automatically from the URL. It can also be used
+to reload captchas.  Refer to Server function documentation for details, or
+take a look at the example in "example" subdirectory.
+
 
 Examples
 --------

M captcha.go → captcha.go

@@ -1,5 +1,44 @@
 // Package captcha implements generation and verification of image and audio
 // CAPTCHAs.
+//
+// A captcha solution is the sequence of digits 0-9 with the defined length.
+// There are two captcha representations: image and audio.
+//
+// An image representation is a PNG-encoded image with the solution printed on
+// it in such a way that makes it hard for computers to solve it using OCR.
+//
+// An audio representation is a WAVE-encoded (8 kHz unsigned 8-bit) sound
+// with the spoken solution (currently in English). To make it hard for
+// computers to solve audio captcha, the voice that pronounces numbers has
+// random speed and pitch, and there is a randomly generated background noise
+// mixed into the sound.
+//
+// This package doesn't require external files or libraries to generate captcha
+// representations; it is self-contained.
+//
+// To make captchas one-time, the package includes a memory storage that stores
+// captcha ids, their solutions, and expiration time. Used captchas are removed
+// from the store immediately after calling Verify or VerifyString, while
+// unused captchas (user loaded a page with captcha, but didn't submit the
+// form) are collected automatically after the predefined expiration time.
+// Developers can also provide custom store (for example, which saves captcha
+// ids and solutions in database) by implementing Store interface and
+// registering the object with SetCustomStore.
+//
+// Captchas are created by calling New, which returns the captcha id.  Their
+// representations, though, are created on-the-fly by calling WriteImage or
+// WriteAudio functions. Created representations are not stored anywhere, so
+// subsequent calls to these functions with the same id will write the same
+// captcha solution, but with a different random representation. Reload
+// function will create a new different solution for the provided captcha,
+// allowing users to "reload" captcha if they can't solve the displayed one
+// without reloading the whole page.  Verify and VerifyString are used to
+// verify that the given solution is the right one for the given captcha id.
+//
+// Server provides an http.Handler which can serve image and audio
+// representations of captchas automatically from the URL. It can also be used
+// to reload captchas.  Refer to Server function documentation for details, or
+// take a look at the example in "example" subdirectory.
 package captcha
 
 import (
@@ -185,9 +224,10 @@ w.Header().Set("Content-Type", "application/octet-stream")
 		} else {
 			w.Header().Set("Content-Type", "audio/x-wav")
 		}
-		//err = WriteAudio(buf, id)
+		//err = WriteAudio(w, id)
 		//XXX(dchest) Workaround for Chrome: it wants content-length,
 		//or else will start playing NOT from the beginning.
+		//File issue: http://code.google.com/p/chromium/issues/detail?id=80565
 		d := globalStore.Get(id, false)
 		if d == nil {
 			err = ErrNotFound