Documentation fixes.

src/dom/dom.js

@@ -290,9 +290,16 @@
   }
 
   /**
-   *  Element.toggle(@element) -> Element
+   *  Element.toggle(@element[, bool]) -> Element
    *
-   *  Toggles the visibility of `element`. Returns `element`.
+   *  Toggles the CSS `display` of `element`. Returns `element`.
+   *  
+   *  Switches an element's CSS `display` between `none` and its inherited
+   *  value (usually `block` or `inline`).
+   *
+   *  By default, `toggle` will switch the display to the opposite of its
+   *  current state, but will use the `bool` argument instead if it's
+   *  provided (`true` to show the element, `false` to hide it).
    *  
    *  ##### Examples
    *  
@@ -305,6 +312,10 @@
    *      $('error-message').toggle();
    *      // -> Element (and displays div#error-message)
    *  
+   *      $('error-message).toggle(true);
+   *      // -> Element (and displays div#error-message, no matter what its
+   *      //    previous state)
+   *  
    *  Toggle multiple elements using [[Enumerable#each]]:
    *  
    *      ['error-message', 'welcome-message'].each(Element.toggle);
@@ -314,6 +325,11 @@
    *  
    *      $('error-message', 'welcome-message').invoke('toggle');
    *      // -> [Element, Element]
+   *  
+   *      $('error-message', 'welcome-message').invoke('toggle', false);
+   *      // -> [Element, Element] (and hides both elements, no matter what
+   *            their previous state)
+   *  
    *
    *  ##### Notes
    *  
@@ -331,7 +347,7 @@
    *      
    *      <div id="hidden-by-css"></div>
    *  
-   *      $('hidden-by-css').toggle(); // WONT' WORK!
+   *      $('hidden-by-css').toggle(); // WON'T WORK!
    *      // -> Element (div#hidden-by-css is still hidden!)
   **/
   function toggle(element, bool) {
@@ -2485,9 +2501,13 @@
   }
 
   /**
-   *  Element.toggleClassName(@element, className) -> Element
+   *  Element.toggleClassName(@element, className[, bool]) -> Element
    *
    *  Toggles the presence of CSS class `className` on `element`.
+   *  
+   *  By default, `toggleClassName` will flip to the opposite state, but
+   *  will use `bool` instead if it's given; `true` will add the class name
+   *  and `false` will remove it.
    *
    *  ##### Examples
    *  
@@ -2500,10 +2520,13 @@
    *      // -> false
    *      
    *      $('mutsu').toggleClassName('fruit');
-   *      // -> element
+   *      // -> Element
    *      
    *      $('mutsu').hasClassName('fruit');
    *      // -> true
+   *  
+   *      $('mutsu').toggleClassName('fruit', true);
+   *      // -> Element (keeps the "fruit" class name that was already there)
   **/
   function toggleClassName(element, className, bool) {
     if (!(element = $(element))) return;

src/dom/event.js

@@ -99,7 +99,7 @@
       // (Though Opera supports both systems, the event object appears to be
       // the same no matter which system is used. That means that this function
       // will always return `true` in Opera, but that's OK; it keeps us from
-      // having to do a browser sniff.
+      // having to do a browser sniff.)
       isIELegacyEvent = function(event) {
         return !(event instanceof window.Event);
       };
@@ -151,6 +151,7 @@
 
   /**
    *  Event.isLeftClick(@event) -> Boolean
+   *  - event (Event): An Event object
    *
    *  Determines whether a button-related mouse event involved the left
    *  mouse button.
@@ -163,6 +164,7 @@
 
   /**
    *  Event.isMiddleClick(@event) -> Boolean
+   *  - event (Event): An Event object
    *
    *  Determines whether a button-related mouse event involved the middle
    *  mouse button.
@@ -171,11 +173,12 @@
 
   /**
    *  Event.isRightClick(@event) -> Boolean
+   *  - event (Event): An Event object
    *
    *  Determines whether a button-related mouse event involved the right
    *  mouse button.
    *
-   *  Keep in mind that the "left" mouse button is actually the "secondary"
+   *  Keep in mind that the "right" mouse button is actually the "secondary"
    *  mouse button. When a mouse is in left-handed mode, the browser will
    *  report clicks of the _left_ button as "left-clicks."
   **/
@@ -255,11 +258,11 @@
    *  
    *  ##### Example
    *  
-   *  Here's a simple code that lets you click everywhere on the page and hides
-   *  the closest-fitting paragraph around your click (if any).
+   *  Here's a simple example that lets you click everywhere on the page and
+   *  hides the closest-fitting paragraph around your click (if any).
    *  
    *      document.observe('click', function(event) {
-   *        var element = Event.findElement(event, 'p');
+   *        var element = event.findElement('p');
    *        if (element != document)
    *          $(element).hide();
    *      });
@@ -433,6 +436,7 @@
 
     /**
      *  Event.extend(@event) -> Event
+     *  - event (Event): An Event object
      *  
      *  Extends `event` with all of the methods contained in `Event.Methods`.
      *