Fixed required field description and added better example docs for ajax:aborted events.

Author: JangoSteve

src/rails.js

@@ -13,8 +13,8 @@
  * The `ajax:aborted:file` event allows you to bind your own handler to process the form submission however you wish.
  *
  * Ex:
- *     $('form').live('ajax:aborted:file', function(){
- *       // Implement own remote file-transfer handler here.
+ *     $('form').live('ajax:aborted:file', function(event, elements){
+ *       // Implement own remote file-transfer handler here for non-blank file inputs passed in `elements`.
  *       // Returning false in this handler tells rails.js to disallow standard form submission
  *       return false;
  *     });
@@ -27,17 +27,18 @@
  * Required fields in rails.js
  * ===========================
  *
- * If any required input field (input[required]) is blank then the AJAX form submission is cancelled.
- * Note that unlike file uploads case here the whole form submission is cancelled ,by default.
+ * If any blank required inputs (required="required") are detected in the remote form, the whole form submission
+ * is canceled. Note that this is unlike non-blank file inputs, which still allow non-AJAX form submission.
  *
  * The `ajax:aborted:required` event allows you to bind your own handler to inform the user of blank required inputs.
  *
- * !! Note that Opera does not fire the form's submit event if there are blank required inputs,
- *    so this event may never get fired in Opera.
+ * !! Note that Opera does not fire the form's submit event if there are blank required inputs, so this event may never
+ *    get fired in Opera. This event is what causes other browsers to exhibit the same submit-aborting behavior.
  *
  * Ex:
- *     $('form').live('ajax:aborted:required', function(){
- *       // Returning false in this handler tells rails.js to submit the form anyway
+ *     $('form').live('ajax:aborted:required', function(event, elements){
+ *       // Returning false in this handler tells rails.js to submit the form anyway.
+ *       // The blank required inputs are passed to this function in `elements`.
  *       return ! confirm("Would you like to submit the form with missing info?");
  *     });
  */