README.rdoc in larynx-0.1.2 vs README.rdoc in larynx-0.1.3

@@ -102,11 +102,11 @@
     end
   end
 
   Larynx.answer {|call| Guess.run(call) }
 
-The Form class wraps up many handy conventions into a pleasant DSL in which allows you to control the user
+The Form class wraps up many handy conventions into a pleasant DSL in which allows you to control the caller
 interaction more easily.
 
 Save your app into file and run larynx comand to start the app server ready to receive calls.
 
   $ larynx app.rb
@@ -165,27 +165,81 @@
 
 The class method initialises some things for you and then calls <tt>run</tt> on the instance. From
 there its up to you. You can use all the commands directly rather than call them on the call
 instance.
 
-== Form Class
-
-
-
 == Event Hooks
 
 The Application and Form classes have a couple of useful event hook methods available which are
 
   class MyApp < Larynx::Application
     def run
     end
 
     def dtmf_received(input)
-      # input is the button the user just pushed
+      # input is the button the caller just pushed
     end
 
     def hungup
       # application specific handling of a hangup
     end
   end
+
+== Form Class
+
+The Form class is a sublcass of the Application class with some added goodness. You can use the field
+DSL to abstract away a lot of the reptitive work and more difficult asynchronous stuff you would have
+to handle yourself.
+
+When collection input from the caller you are usually needing to do one or more of a few things.
+
+These are:
+1. Set-up something before the caller is prompted for the information.
+2. Repeat the prompt for input if the caller doesn't enter anything or does not enter enough digits.
+3. Validate the input for constraints beyond length such as a range or finding a matching database record.
+4. Perform some task, perhaps say something, if the input is invalid but before the prompt is repeated.
+5. Handle the next action if the input is valid
+6. Handle the next action if the caller fails enter valid input after a number of attempts.
+
+You define these tasks as callbacks for each type of action, be it setup, validate, invalid, success or failure.
+These callbacks are run in the scope of the form class instance each time so that they can access user
+defined methods or instance variables you need.
+
+Each field defined becomes an attribute on the form class instance which you can use at any time. The value
+is set to the caller input after each prompt, just use the field attribute method to retrieve it. A form may
+have as many fields defined you as need. Though the idea would be to group fields with a particular purpose
+together and define another form for unrelated fields.
+
+Lets look at a simple Form class with empty callbacks in place.
+
+  class MyApp < Larynx::Form
+    field(:my_field, :attempts => 3, :length => 1) do
+      prompt :speak => 'Please enter a value.'
+
+      setup do
+        # run once when the field is starts
+      end
+
+      validate do
+        # run when the input is of a valid length
+      end
+
+      invalid do
+        # run when the input is not a valid length or the validate block returns false
+      end
+
+      success do
+        # run when the input is a valid length the validate block, if defined, returns true
+      end
+
+      failure do
+        # run when the maximum attempts has been reached and valid input has not been entered
+      end
+    end
+  end
+
+This form will do the following when run:
+* Define a field attribute method called <tt>my_field</tt>
+* Atempt to obtain the field value up to 3 times if the caller fails to successfully enter it
+* Accept a single digit value as complete and valid intput