Permalink
Browse files

Documentation fixes.

  • Loading branch information...
1 parent afdb2c0 commit 38cafcc1dd6fe2ff172febb8f613e5fed3a7ff62 @savetheclocktower savetheclocktower committed Apr 19, 2011
Showing with 37 additions and 10 deletions.
  1. +28 −5 src/dom/dom.js
  2. +9 −5 src/dom/event.js
View
@@ -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;
View
@@ -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`.
*

0 comments on commit 38cafcc

Please sign in to comment.