DOM.$ -> DOM.constructor, update jsdocs

src/element/children.js

@@ -32,7 +32,7 @@ function makeMethod(methodName, validSelectorType) {
 /**
  * Return child element by index filtered by optional selector
  * @param  {Number} index child index
- * @return {$Element} a matched child
+ * @return {$Element} A matched child element
  * @function
  * @example
  * ul.child(0);  // => the first <li>
@@ -44,7 +44,7 @@ $Element.prototype.child = makeMethod("child", "number");
 /**
  * Fetch children elements filtered by optional selector
  * @param  {String} [selector] css selector
- * @return {Array.<$Element>} an array of all matched elements
+ * @return {Array.<$Element>} An array of all matched elements
  * @function
  * @example
  * ul.children();       // => array with all child <li>

src/element/classes.js

@@ -6,8 +6,8 @@ const normalizedClass = node => (" " + node.className + " ").replace(REGEXP_SPAC
 
 /**
  * Check if element contains a class name
- * @param  {String}   className class name to verify
- * @return {Boolean}  <code>true</code> if the element contains the class
+ * @param  {String} className class name to verify
+ * @return {Boolean} `true` if the element contains the class
  * @example
  * link.hasClass("foo");
  */
@@ -29,7 +29,7 @@ $Element.prototype.hasClass = function(className) {
 /**
  * Add class(es) to element
  * @param  {...String} className class name to add
- * @return {$Element}
+ * @return {$Element} Self
  * @example
  * link.addClass("foo", "bar");
  */
@@ -54,7 +54,7 @@ $Element.prototype.addClass = function(...classNames) {
 /**
  * Remove class(es) from element
  * @param  {...String} className class name to remove
- * @return {$Element}
+ * @return {$Element} Self
  * @example
  * link.removeClass("foo", "bar");
  */
@@ -78,9 +78,9 @@ $Element.prototype.removeClass = function(...classNames) {
 
 /**
  * Toggle a class on element
- * @param  {String}  className class name to toggle
- * @param  {Boolean} [force] if <code>true</code> then adds the className; if <code>false</code> - removes it
- * @return {Boolean} <code>true</code> if the className is now present, and <code>false</code> otherwise.
+ * @param  {String} className class name to toggle
+ * @param  {Boolean} [force] if `true` then adds the className; if `false` - removes it
+ * @return {Boolean} `true` if the `className` is now present, and `false` otherwise.
  * @example
  * link.toggleClass("foo");
  * link.toggleClass("bar", true);

src/element/css.js

@@ -5,9 +5,9 @@ import HOOK from "../util/stylehooks";
 
 /**
  * CSS properties accessor for an element
- * @param  {String|Object}      name    style property name or key/value object
- * @param  {String|Function}    [value] style property value or functor
- * @return {String|$Element} a property value or reference to <code>this</code>
+ * @param  {String|Object} name Style property name or key/value object
+ * @param  {String|Function} [value] Style property value or functor
+ * @return {String|$Element} Property value or self
  * @example
  * link.css("color");                 // => element color property
  * link.css("box-sizing");            // => value of "box-sizing" (no vendor prefix needed)

src/element/manipulation.js

@@ -55,7 +55,7 @@ function makeMethod(fastStrategy, requiresParent, strategy) {
 /**
  * Insert HTMLString or {@link $Element} after the current element
  * @param {...Mixed} contents HTMLString, {@link $Element}, Array.<{@link $Element}> or functor
- * @return {$Element}
+ * @return {$Element} Self
  * @function
  * @example
  * var link = DOM.create("a");                   // <a></a>
@@ -69,7 +69,7 @@ $Element.prototype.after = makeMethod("afterend", true, (node, relatedNode) => {
 /**
  * Insert HTMLString or {@link $Element} before the current element
  * @param {...Mixed} contents HTMLString, {@link $Element}, Array.<{@link $Element}> or functor
- * @return {$Element}
+ * @return {$Element} Self
  * @function
  * @example
  * var link = DOM.create("a");                    // <a></a>
@@ -83,7 +83,7 @@ $Element.prototype.before = makeMethod("beforebegin", true, (node, relatedNode)
 /**
  * Prepend HTMLString or {@link $Element} to the current element
  * @param {...Mixed} contents HTMLString, {@link $Element}, Array.<{@link $Element}> or functor
- * @return {$Element}
+ * @return {$Element} Self
  * @function
  * @example
  * var link = DOM.create("a>`foo`");               // <a>foo</a>
@@ -97,7 +97,7 @@ $Element.prototype.prepend = makeMethod("afterbegin", false, (node, relatedNode)
 /**
  * Append HTMLString or {@link $Element} to the current element
  * @param {...Mixed} contents HTMLString, {@link $Element}, Array.<{@link $Element}> or functor
- * @return {$Element}
+ * @return {$Element} Self
  * @function
  * @example
  * var link = DOM.create("a>`foo`");              // <a>foo</a>
@@ -111,7 +111,7 @@ $Element.prototype.append = makeMethod("beforeend", false, (node, relatedNode) =
 /**
  * Replace current element with HTMLString or {@link $Element}
  * @param {Mixed} content HTMLString, {@link $Element}, Array.<{@link $Element}> or functor
- * @return {$Element}
+ * @return {$Element} Self
  * @function
  * @example
  * var div = DOM.create("div>span>`foo`");      // <div><span>foo</span></div>

src/element/offset.js

@@ -3,7 +3,7 @@ import { WINDOW } from "../const";
 
 /**
  * Calculates offset of the current element
- * @return {Object} object with left, top, bottom, right, width and height properties
+ * @return {Object} An object with left, top, bottom, right, width and height properties
  * @example
  * el.offset(); // => {left: 1, top: 2, right: 3, bottom: 4, width: 2, height: 2}
  */

src/element/traversing.js

@@ -38,8 +38,8 @@ function makeMethod(methodName, propertyName, all) {
 
 /**
  * Find next sibling element filtered by optional selector
- * @param {String} [selector] css selector
- * @return {$Element} matched element wrapper
+ * @param {String} [selector] CSS selector
+ * @return {$Element} Matched element
  * @function
  * @example
  * var div = DOM.create("div>a+b+i"); // <div><a></a><b></b><i></i></div>
@@ -51,8 +51,8 @@ $Element.prototype.next = makeMethod("next", "nextElementSibling");
 
 /**
  * Find previous sibling element filtered by optional selector
- * @param {String} [selector] css selector
- * @return {$Element} matched element wrapper
+ * @param {String} [selector] CSS selector
+ * @return {$Element} Matched element
  * @function
  * @example
  * var div = DOM.create("div>b+i+a"); // <div><b></b><i></i><a></a></div>
@@ -64,8 +64,8 @@ $Element.prototype.prev = makeMethod("prev", "previousElementSibling");
 
 /**
  * Find all next sibling elements filtered by optional selector
- * @param {String} [selector] css selector
- * @return {Array.<$Element>} an array of all matched element wrappers
+ * @param {String} [selector] CSS selector
+ * @return {Array.<$Element>} An array of all matched elements
  * @function
  * @example
  * var div = DOM.create("div>a+i+b+i"); // <div><a></a><i></i><b></b><i></i></div>
@@ -77,8 +77,8 @@ $Element.prototype.nextAll = makeMethod("nextAll", "nextElementSibling", true);
 
 /**
  * Find all previous sibling elements filtered by optional selector
- * @param {String} [selector] css selector
- * @return {Array.<$Element>} an array of all matched element wrappers
+ * @param {String} [selector] CSS selector
+ * @return {Array.<$Element>} An array of all matched elements
  * @function
  * @example
  * var div = DOM.create("div>a+i+b+i"); // <div><i></i><b></b><i></i><a></a></div>
@@ -90,8 +90,8 @@ $Element.prototype.prevAll = makeMethod("prevAll", "previousElementSibling", tru
 
 /**
  * Find the closest ancestor of the current element (or the current element itself) which matches selector
- * @param {String} [selector] css selector
- * @return {$Element} matched element wrapper
+ * @param {String} [selector] CSS selector
+ * @return {$Element} Matched element
  * @function
  * @example
  * var div = DOM.create("div.foo>div.bar>a"); // <div class="foo"><div class="bar"><a></a></div></div>

src/element/value.js

@@ -3,8 +3,8 @@ import { every } from "../util/index";
 
 /**
  * Read or write inner content of the element
- * @param  {String} [content] value to set to
- * @return {$Element|String} self or inner content value
+ * @param  {HTMLString} [content] Value to set to
+ * @return {$Element|String} Self or inner content value
  * @function
  * @example
  * var div = DOM.create("div>a+b"); // <div><a></a><b></b></div>
@@ -62,7 +62,7 @@ $Element.prototype.value = function(content) {
 
 /**
  * Clears all children
- * @return {$Element} self
+ * @return {$Element} Self
  * @function
  * @example
  * var div = DOM.create("div>a+b"); // <div><a></a><b></b></div>

src/element/visibility.js

@@ -53,9 +53,9 @@ function makeMethod(methodName, condition) {
 
 /**
  * Show an element using CSS3 transition or animation
- * @param {String}   [animationName]  CSS animation to apply during transition
- * @param {Function} [callback]       function that executes when animation is done
- * @return {$Element}
+ * @param {String} [animationName] CSS animation name to apply during transition
+ * @param {Function} [callback] function that executes when animation is done
+ * @return {$Element} Self
  * @function
  * @example
  * link.show(); // displays element
@@ -72,9 +72,9 @@ $Element.prototype.show = makeMethod("show", false);
 
 /**
  * Hide an element using CSS3 transition or animation
- * @param {String}   [animationName]  CSS animation to apply during transition
- * @param {Function} [callback]       function that executes when animation is done
- * @return {$Element}
+ * @param {String} [animationName] CSS animation name to apply during transition
+ * @param {Function} [callback] function that executes when animation is done
+ * @return {$Element} Self
  * @function
  * @example
  * link.hide(); // hides element

src/index.js

@@ -20,7 +20,7 @@ const _DOM = WINDOW.DOM;
  * // bodyEl is an instance of $Element
  * bodyEl.hide();
  */
-DOM.$ = (node) => {
+DOM.constructor = (node) => {
     const nodeType = node && node.nodeType;
 
     if (nodeType === ELEMENT_NODE) {

src/node/clone.js

@@ -5,21 +5,21 @@ import { MethodError } from "../errors";
 
 /**
  * Clone element
- * @param {Boolean} deep <code>true</code> if all children should also be cloned, or <code>false</code> otherwise
- * @return {$Node} a clone of the current element
+ * @param  {Boolean} deepCopy `true` when all children should also be cloned, otherwise `false`
+ * @return {$Node} A clone of the current element
  * @example
  * ul.clone(true);  // => clone of <ul> with all it's children
  * ul.clone(false); // => clone of <ul> element ONLY
  */
-$Node.prototype.clone = function(deep) {
-    if (typeof deep !== "boolean") {
+$Node.prototype.clone = function(deepCopy) {
+    if (typeof deepCopy !== "boolean") {
         throw new MethodError("clone", arguments);
     }
 
     const node = this[0];
 
     if (node) {
-        const clonedNode = node.cloneNode(deep);
+        const clonedNode = node.cloneNode(deepCopy);
 
         if (this instanceof $Element) {
             return new $Element(clonedNode);

src/node/contains.js

@@ -3,9 +3,9 @@ import { $Element } from "../element/index";
 import { MethodError } from "../errors";
 
 /**
- * Check if element is inside of context
- * @param  {$Node} element element to check
- * @return {Boolean} returns <code>true</code> if success and <code>false</code> otherwise
+ * Check if an element is inside of the current context
+ * @param  {$Node} element Element to check
+ * @return {Boolean} `true` if success and `false` otherwise
  * @example
  * DOM.contains(DOM.find("body")); // => true
  * DOM.find("body").contains(DOM); // => false

src/node/find.js

@@ -62,9 +62,9 @@ function makeMethod(methodName, all) {
 }
 
 /**
- * Find the first matched element by css selector
- * @param  {String} selector css selector
- * @return {$Element} the first matched element
+ * Find the first matched element in the current context by a CSS selector
+ * @param  {String} selector CSS selector
+ * @return {$Element} The first matched element
  * @function
  * @example
  * var body = DOM.find("body");  // => <body> wrapper
@@ -74,9 +74,9 @@ function makeMethod(methodName, all) {
 $Node.prototype.find = makeMethod("find", "");
 
 /**
- * Find all matched elements by css selector
- * @param  {String} selector css selector
- * @return {Array.<$Element>} an array of element wrappers
+ * Find all matched elements in the current context by a CSS selector
+ * @param  {String} selector CSS selector
+ * @return {Array.<$Element>} An array of matched elements
  * @function
  * @example
  * DOM.findAll("a");         // => all links in the document

src/node/fire.js

@@ -4,13 +4,13 @@ import EventHandler from "../util/eventhandler";
 import HOOK from "../util/eventhooks";
 
 /**
- * Triggers an event of specific type with optional extra arguments
- * @param  {String}   type    type of event
- * @param  {Object}  [detail] custom event data
+ * Trigger an event of specific type with optional data
+ * @param  {String} type Type of event
+ * @param  {Object} [detail] Custom event data
  * @return {Boolean} `true` if default event action was NOT prevented
  * @example
- * link.fire("click");                   // fire click event
- * link.fire("my:event", {a: "b"}, 123); // fire "my:event" with arguments
+ * link.fire("click");              // fire click event
+ * link.fire("my:event", {a: "b"}); // fire "my:event" with custom data
  */
 $Node.prototype.fire = function(type, detail) {
     const node = this[0];

src/node/get.js

@@ -6,9 +6,9 @@ import PROP from "../util/accessorhooks";
 
 /**
  * Get property or attribute value by name
- * @param  {String|Array}  name  property or attribute name or array of names
- * @param  {Object} [defaultValue] default value if returned is `null`
- * @return {String|Object} a value of property or attribute
+ * @param  {String|Array} name Property or attribute name or array of names
+ * @param  {Object} [defaultValue] Default value if returned is `null`
+ * @return {Object} Value of property or attribute
  * @example
  * link.get("title");       // => property title
  * link.get("data-custom"); // => custom attribute data-custom

src/node/on.js

@@ -5,11 +5,11 @@ import { isArray } from "../util/index";
 
 /**
  * Bind a DOM event listener
- * @param  {String}        type        event type with optional selector
- * @param  {Object|String} [options]   event options object or css selector to match on
- * @param  {Array}         [args]      array of handler arguments to pass into the callback
- * @param  {Function}      callback    event callback
- * @return {$Element}
+ * @param  {String} type Event type
+ * @param  {Object|String} [options] Event options object or css selector to match on
+ * @param  {Array} [args] Array of handler arguments to pass into the callback
+ * @param  {Function} callback Event listener callback
+ * @return {Function} Functor to cancel the listener
  * @example
  * link.on("focus", function() {
  *     // do something on focus
@@ -22,6 +22,14 @@ import { isArray } from "../util/index";
  * link.on("click", "span", ["currentTarget"], function(span) {
  *     // <span> is the element was clicked
  * });
+ *
+ * link.on("blur", {once: true}, function() {
+ *     // event fired only once
+ * });
+ *
+ * link.on("mousedown", {capture: true}, function() {
+ *     // event fired on capturing phase
+ * });
  */
 $Node.prototype.on = function(type, options, args, callback) {
     if (typeof type === "string") {

src/node/set.js

@@ -6,9 +6,9 @@ import PROP from "../util/accessorhooks";
 
 /**
  * Set property/attribute value by name
- * @param {String|Object|Array}   name    property/attribute name
- * @param {String|Function}       value   property/attribute value or functor
- * @return {$Node}
+ * @param {String|Object|Array|Function} name property/attribute name
+ * @param {String|Function} value property/attribute value or functor
+ * @return {$Node} Self
  * @example
  * link.set("title", "mytitle");   // set title property
  * link.set("data-custom", "foo"); // set custom attribute data-custom