From fefc2b728d802bb6586fa3bdefea7c8881ec3b2f Mon Sep 17 00:00:00 2001 From: Andrew Dupont Date: Mon, 17 Aug 2009 15:53:33 -0500 Subject: [PATCH] Change PDoc syntax for "methodized" methods. --- src/dom/dom.js | 130 +++++++++++++++++++++++----------------------- src/dom/event.js | 26 +++++----- src/dom/form.js | 30 +++++------ src/lang/array.js | 1 + src/lang/hash.js | 1 + 5 files changed, 95 insertions(+), 93 deletions(-) diff --git a/src/dom/dom.js b/src/dom/dom.js index ef84be7..861eb9f 100644 --- a/src/dom/dom.js +++ b/src/dom/dom.js @@ -111,7 +111,7 @@ Element.idCounter = 1; Element.Methods = { /** - * Element#visible(@element) -> boolean + * Element.visible(@element) -> boolean * * Tells whether `element` is visible (i.e., whether its inline `display` * CSS property is set to `none`. @@ -121,7 +121,7 @@ Element.Methods = { }, /** - * Element#toggle(@element) -> Element + * Element.toggle(@element) -> Element * * Toggles the visibility of `element`. Returns `element`. **/ @@ -133,7 +133,7 @@ Element.Methods = { /** - * Element#hide(@element) -> Element + * Element.hide(@element) -> Element * * Sets `display: none` on `element`. Returns `element`. **/ @@ -144,7 +144,7 @@ Element.Methods = { }, /** - * Element#show(@element) -> Element + * Element.show(@element) -> Element * * Removes `display: none` on `element`. Returns `element`. **/ @@ -155,7 +155,7 @@ Element.Methods = { }, /** - * Element#remove(@element) -> Element + * Element.remove(@element) -> Element * * Completely removes `element` from the document and returns it. **/ @@ -166,7 +166,7 @@ Element.Methods = { }, /** - * Element#update(@element[, newContent]) -> Element + * Element.update(@element[, newContent]) -> Element * * Replaces _the content_ of `element` with the `newContent` argument and * returns `element`. @@ -262,7 +262,7 @@ Element.Methods = { })(), /** - * Element#replace(@element[, newContent]) -> Element + * Element.replace(@element[, newContent]) -> Element * * Replaces `element` _itself_ with `newContent` and returns `element`. * @@ -284,7 +284,7 @@ Element.Methods = { }, /** - * Element#insert(@element, content) -> Element + * Element.insert(@element, content) -> Element * - content (String | Object): The content to insert. * * Inserts content at a specific point relative to `element`. @@ -334,7 +334,7 @@ Element.Methods = { }, /** - * Element#wrap(@element, wrapper[, attributes]) -> Element + * Element.wrap(@element, wrapper[, attributes]) -> Element * - wrapper (Element | String): An element to wrap `element` inside, or * else a string representing the tag name of an element to be created. * - attributes (Object): A set of attributes to apply to the wrapper @@ -355,7 +355,7 @@ Element.Methods = { }, /** - * Element#inspect(@element) -> String + * Element.inspect(@element) -> String * * Returns the debug-oriented string representation of `element`. **/ @@ -371,7 +371,7 @@ Element.Methods = { }, /** - * Element#recursivelyCollect(element, property) -> [Element...] + * Element.recursivelyCollect(@element, property) -> [Element...] * * Recursively collects elements whose relationship to `element` is * specified by `property`. `property` has to be a _property_ (a method @@ -388,7 +388,7 @@ Element.Methods = { }, /** - * Element#ancestors(@element) -> [Element...] + * Element.ancestors(@element) -> [Element...] * * Collects all of `element`'s ancestors and returns them as an array of * elements. @@ -398,7 +398,7 @@ Element.Methods = { }, /** - * Element#descendants(@element) -> [Element...] + * Element.descendants(@element) -> [Element...] * * Collects all of element's descendants and returns them as an array of * elements. @@ -408,7 +408,7 @@ Element.Methods = { }, /** - * Element#firstDescendant(@element) -> Element + * Element.firstDescendant(@element) -> Element * * Returns the first child that is an element. * @@ -422,7 +422,7 @@ Element.Methods = { }, /** - * Element#childElements(@element) -> [Element...] + * Element.immediateDescendants(@element) -> [Element...] * * Collects all of `element`'s immediate descendants (i.e., children) and * returns them as an array of elements. @@ -435,7 +435,7 @@ Element.Methods = { }, /** - * Element#previousSiblings(@element) -> [Element...] + * Element.previousSiblings(@element) -> [Element...] * * Collects all of `element`'s previous siblings and returns them as an * array of elements. @@ -445,7 +445,7 @@ Element.Methods = { }, /** - * Element#nextSiblings(@element) -> [Element...] + * Element.nextSiblings(@element) -> [Element...] * * Collects all of `element`'s next siblings and returns them as an array * of elements. @@ -455,7 +455,7 @@ Element.Methods = { }, /** - * Element#siblings(@element) -> [Element...] + * Element.siblings(@element) -> [Element...] * Collects all of element's siblings and returns them as an array of * elements. **/ @@ -466,7 +466,7 @@ Element.Methods = { }, /** - * Element#match(@element, selector) -> boolean + * Element.match(@element, selector) -> boolean * - selector (String): A CSS selector. * * Checks if `element` matches the given CSS selector. @@ -478,8 +478,8 @@ Element.Methods = { }, /** - * Element#up(@element[, expression[, index = 0]]) -> Element - * Element#up(@element[, index = 0]) -> Element + * Element.up(@element[, expression[, index = 0]]) -> Element + * Element.up(@element[, index = 0]) -> Element * - expression (String): A CSS selector. * * Returns `element`'s first ancestor (or the Nth ancestor, if `index` @@ -496,8 +496,8 @@ Element.Methods = { }, /** - * Element#down(@element[, expression[, index = 0]]) -> Element - * Element#down(@element[, index = 0]) -> Element + * Element.down(@element[, expression[, index = 0]]) -> Element + * Element.down(@element[, index = 0]) -> Element * - expression (String): A CSS selector. * * Returns `element`'s first descendant (or the Nth descendant, if `index` @@ -513,8 +513,8 @@ Element.Methods = { }, /** - * Element#previous(@element[, expression[, index = 0]]) -> Element - * Element#previous(@element[, index = 0]) -> Element + * Element.previous(@element[, expression[, index = 0]]) -> Element + * Element.previous(@element[, index = 0]) -> Element * - expression (String): A CSS selector. * * Returns `element`'s first previous sibling (or the Nth, if `index` @@ -531,8 +531,8 @@ Element.Methods = { }, /** - * Element#next(@element[, expression[, index = 0]]) -> Element - * Element#next(@element[, index = 0]) -> Element + * Element.next(@element[, expression[, index = 0]]) -> Element + * Element.next(@element[, index = 0]) -> Element * - expression (String): A CSS selector. * * Returns `element`'s first following sibling (or the Nth, if `index` @@ -550,7 +550,7 @@ Element.Methods = { /** - * Element#select(@element, selector...) -> [Element...] + * Element.select(@element, selector...) -> [Element...] * - selector (String): A CSS selector. * * Takes an arbitrary number of CSS selectors and returns an array of @@ -574,7 +574,7 @@ Element.Methods = { }, /** - * Element#identify(@element) -> String + * Element.identify(@element) -> String * * Returns `element`'s ID. If `element` does not have an ID, one is * generated, assigned to `element`, and returned. @@ -589,7 +589,7 @@ Element.Methods = { }, /** - * Element#readAttribute(@element, attributeName) -> String | null + * Element.readAttribute(@element, attributeName) -> String | null * * Returns the value of `element`'s attribute with the given name. **/ @@ -608,8 +608,8 @@ Element.Methods = { }, /** - * Element#writeAttribute(@element, attribute[, value = true]) -> Element - * Element#writeAttribute(@element, attributes) -> Element + * Element.writeAttribute(@element, attribute[, value = true]) -> Element + * Element.writeAttribute(@element, attributes) -> Element * * Adds, changes, or removes attributes passed as either a hash or a * name/value pair. @@ -635,7 +635,7 @@ Element.Methods = { }, /** - * Element#getHeight(@element) -> Number + * Element.getHeight(@element) -> Number * * Returns the height of `element`. **/ @@ -644,7 +644,7 @@ Element.Methods = { }, /** - * Element#getWidth(@element) -> Number + * Element.getWidth(@element) -> Number * * Returns the width of `element`. **/ @@ -653,7 +653,7 @@ Element.Methods = { }, /** - * Element#classNames(@element) -> [String...] + * Element.classNames(@element) -> [String...] * * Returns a new instance of [[Element.ClassNames]], an [[Enumerable]] * object used to read and write CSS class names of `element`. @@ -663,7 +663,7 @@ Element.Methods = { }, /** - * Element#hasClassName(@element, className) -> Boolean + * Element.hasClassName(@element, className) -> Boolean * * Checks whether `element` has the given CSS class name. **/ @@ -675,7 +675,7 @@ Element.Methods = { }, /** - * Element#addClassName(@element, className) -> Element + * Element.addClassName(@element, className) -> Element * * Adds a CSS class to `element`. **/ @@ -687,7 +687,7 @@ Element.Methods = { }, /** - * Element#removeClassName(@element, className) -> Element + * Element.removeClassName(@element, className) -> Element * * Removes a CSS class from `element`. **/ @@ -699,7 +699,7 @@ Element.Methods = { }, /** - * Element#toggleClassName(@element, className) -> Element + * Element.toggleClassName(@element, className) -> Element * * Toggles the presence of a CSS class on `element`. **/ @@ -710,7 +710,7 @@ Element.Methods = { }, /** - * Element#cleanWhitespace(@element) -> Element + * Element.cleanWhitespace(@element) -> Element * * Removes whitespace-only text node children from `element`. **/ @@ -727,7 +727,7 @@ Element.Methods = { }, /** - * Element#empty(@element) -> Element + * Element.empty(@element) -> Element * * Tests whether `element` is empty (i.e., contains only whitespace). **/ @@ -736,7 +736,7 @@ Element.Methods = { }, /** - * Element#descendantOf(@element, ancestor) -> Boolean + * Element.descendantOf(@element, ancestor) -> Boolean * * Checks if `element` is a descendant of `ancestor`. **/ @@ -756,7 +756,7 @@ Element.Methods = { }, /** - * Element#scrollTo(@element) -> Element + * Element.scrollTo(@element) -> Element * * Scrolls the window so that `element` appears at the top of the viewport. **/ @@ -768,7 +768,7 @@ Element.Methods = { }, /** - * Element#getStyle(@element, style) -> String | null + * Element.getStyle(@element, style) -> String | null * - style (String): The property name to be retrieved. * * Returns the given CSS property value of `element`. The property can be @@ -788,7 +788,7 @@ Element.Methods = { }, /** - * Element#getOpacity(@element) -> String | null + * Element.getOpacity(@element) -> String | null * * Returns the opacity of the element. **/ @@ -797,7 +797,7 @@ Element.Methods = { }, /** - * Element#setStyle(@element, styles) -> Element + * Element.setStyle(@element, styles) -> Element * * Modifies `element`'s CSS style properties. * @@ -823,7 +823,7 @@ Element.Methods = { }, /** - * Element#setOpacity(@element, value) -> Element + * Element.setOpacity(@element, value) -> Element * * Sets the opacity of `element`. **/ @@ -835,7 +835,7 @@ Element.Methods = { }, /** - * Element#getDimensions(@element) -> Object + * Element.getDimensions(@element) -> Object * * Finds the computed width and height of `element` and returns them as * key/value pairs of an object. @@ -865,7 +865,7 @@ Element.Methods = { }, /** - * Element#makePositioned(@element) -> Element + * Element.makePositioned(@element) -> Element * * Allows for the easy creation of a CSS containing block by setting * `element`'s CSS `position` to `relative` if its initial position is @@ -888,7 +888,7 @@ Element.Methods = { }, /** - * Element#undoPositioned(@element) -> Element + * Element.undoPositioned(@element) -> Element * * Sets `element` back to the state it was in _before_ * [[Element.makePositioned]] was applied to it. @@ -907,7 +907,7 @@ Element.Methods = { }, /** - * Element#makeClipping(@element) -> Element + * Element.makeClipping(@element) -> Element * * Simulates the poorly-supported CSS `clip` property by setting `element`'s * `overflow` value to `hidden`. @@ -922,7 +922,7 @@ Element.Methods = { }, /** - * Element#undoClipping(@element) -> Element + * Element.undoClipping(@element) -> Element * * Sets `element`'s CSS `overflow` property back to the value it had * _before_ [[Element.makeClipping]] was applied. @@ -936,7 +936,7 @@ Element.Methods = { }, /** - * Element#cumulativeOffset(@element) -> Array + * Element.cumulativeOffset(@element) -> Array * * Returns the offsets of `element` from the top left corner of the * document. @@ -955,7 +955,7 @@ Element.Methods = { }, /** - * Element#positionedOffset(@element) -> Array + * Element.positionedOffset(@element) -> Array * * Returns `element`'s offset relative to its closest positioned ancestor * (the element that would be returned by [[Element.getOffsetParent]]). @@ -979,7 +979,7 @@ Element.Methods = { }, /** - * Element#absolutize(@element) -> Element + * Element.absolutize(@element) -> Element * * Turns `element` into an absolutely-positioned element _without_ changing * its position in the page layout. @@ -1008,7 +1008,7 @@ Element.Methods = { }, /** - * Element#relativize(@element) -> Element + * Element.relativize(@element) -> Element * * Turns `element` into a relatively-positioned element without changing * its position in the page layout. @@ -1050,7 +1050,7 @@ Element.Methods = { }, /** - * Element#getOffsetParent(@element) -> Element + * Element.getOffsetParent(@element) -> Element * * Returns `element`'s closest _positioned_ ancestor. If none is found, the * `body` element is returned. @@ -1067,7 +1067,7 @@ Element.Methods = { }, /** - * Element#viewportOffset(@element) -> Array + * Element.viewportOffset(@element) -> Array * * Returns the X/Y coordinates of element relative to the viewport. * @@ -1100,7 +1100,7 @@ Element.Methods = { }, /** - * Element#clonePosition(@element, source[, options]) -> Element + * Element.clonePosition(@element, source[, options]) -> Element * * Clones the position and/or dimensions of `source` onto `element` as * defined by `options`. @@ -1153,12 +1153,12 @@ Element.Methods = { Object.extend(Element.Methods, { /** alias of: Element.select - * Element#getElementsBySelector(@element, selector) -> [Element...] + * Element.getElementsBySelector(@element, selector) -> [Element...] **/ getElementsBySelector: Element.Methods.select, /** alias of: Element.immediateDescendants - * Element#childElements(@element) -> [Element...] + * Element.childElements(@element) -> [Element...] **/ childElements: Element.Methods.immediateDescendants }); @@ -1900,7 +1900,7 @@ Element.Storage = { Element.addMethods({ /** - * Element#getStorage(@element) -> Hash + * Element.getStorage(@element) -> Hash * * Returns the [[Hash]] object that stores custom metadata for this element. **/ @@ -1923,7 +1923,7 @@ Element.addMethods({ }, /** - * Element#store(@element, key, value) -> Element + * Element.store(@element, key, value) -> Element * * Stores a key/value pair of custom metadata on the element. * @@ -1943,7 +1943,7 @@ Element.addMethods({ }, /** - * Element#retrieve(@element, key[, defaultValue]) -> ? + * Element.retrieve(@element, key[, defaultValue]) -> ? * * Retrieves custom metadata set on `element` with [[Element.store]]. * @@ -1963,7 +1963,7 @@ Element.addMethods({ }, /** - * Element#clone(@element, deep) -> Element + * Element.clone(@element, deep) -> Element * - deep (Boolean): Whether to clone `element`'s descendants as well. * * Returns a duplicate of `element`. diff --git a/src/dom/event.js b/src/dom/event.js index bbdb4d1..6801f64 100644 --- a/src/dom/event.js +++ b/src/dom/event.js @@ -28,7 +28,7 @@ * keyboard-related events. * * The functions you're most likely to use a lot are [[Event.observe]], - * [[Event#element]] and [[Event#stop]]. If your web app uses custom events, + * [[Event.element]] and [[Event.stop]]. If your web app uses custom events, * you'll also get a lot of mileage out of [[Event.fire]]. **/ var Event = { @@ -78,7 +78,7 @@ } /** - * Event#isLeftClick(@event) -> Boolean + * Event.isLeftClick(@event) -> Boolean * * Determines whether a button-related mouse event involved the left * mouse button. @@ -90,7 +90,7 @@ function isLeftClick(event) { return _isButton(event, 0) } /** - * Event#isMiddleClick(@event) -> Boolean + * Event.isMiddleClick(@event) -> Boolean * * Determines whether a button-related mouse event involved the middle * mouse button. @@ -98,7 +98,7 @@ function isMiddleClick(event) { return _isButton(event, 1) } /** - * Event#isRightClick(@event) -> Boolean + * Event.isRightClick(@event) -> Boolean * * Determines whether a button-related mouse event involved the right * mouse button. @@ -110,7 +110,7 @@ function isRightClick(event) { return _isButton(event, 2) } /** - * Event#element(@event) -> Element + * Event.element(@event) -> Element * * Returns the DOM element on which the event occurred. **/ @@ -139,7 +139,7 @@ } /** - * Event#findElement(@event, expression) -> Element + * Event.findElement(@event, expression) -> Element * * Returns the first DOM element that matches a given CSS selector — * starting with the element on which the event occurred, then moving up @@ -153,7 +153,7 @@ } /** - * Event#pointer(@event) -> Object + * Event.pointer(@event) -> Object * * Returns the absolute position of the pointer for a mouse event. * @@ -167,7 +167,7 @@ } /** - * Event#pointerX(event) -> Number + * Event.pointerX(@event) -> Number * * Returns the absolute horizontal position of the pointer for a mouse * event. @@ -185,7 +185,7 @@ } /** - * Event#pointerY(event) -> Number + * Event.pointerY(@event) -> Number * * Returns the absolute vertical position of the pointer for a mouse * event. @@ -204,7 +204,7 @@ /** - * Event#stop(@event) -> undefined + * Event.stop(@event) -> undefined * * Stops the event's propagation and prevents its eventual default action * from being triggered. @@ -543,19 +543,19 @@ Element.addMethods({ /** - * Element#fire(@element, eventName[, memo[, bubble = true]]) -> Event + * Element.fire(@element, eventName[, memo[, bubble = true]]) -> Event * See [[Event.fire]]. **/ fire: fire, /** - * Element#observe(@element, eventName, handler) -> Element + * Element.observe(@element, eventName, handler) -> Element * See [[Event.observe]]. **/ observe: observe, /** - * Element#stopObserving(element[, eventName[, handler]]) -> Element + * Element.stopObserving(@element[, eventName[, handler]]) -> Element * See [[Event.stopObserving]]. **/ stopObserving: stopObserving diff --git a/src/dom/form.js b/src/dom/form.js index ff3f610..e165452 100644 --- a/src/dom/form.js +++ b/src/dom/form.js @@ -63,7 +63,7 @@ var Form = { Form.Methods = { /** - * Form#serialize(@form[, options]) -> String | Object + * Form.serialize(@form[, options]) -> String | Object * - options (Object): A list of options that affect the return value * of the method. * @@ -77,7 +77,7 @@ Form.Methods = { }, /** - * Form#getElements(@form) -> [Element...] + * Form.getElements(@form) -> [Element...] * * Returns a collection of all controls within a form. **/ @@ -99,7 +99,7 @@ Form.Methods = { }, /** - * Form#getInputs(@form [, type [, name]]) -> [Element...] + * Form.getInputs(@form [, type [, name]]) -> [Element...] * - type (String): A value for the `type` attribute against which to * filter. * - name (String): A value for the `name` attribute against which to @@ -127,7 +127,7 @@ Form.Methods = { }, /** - * Form#disable(@form) -> Element + * Form.disable(@form) -> Element * * Disables the form as a whole. Form controls will be visible but * uneditable. @@ -139,7 +139,7 @@ Form.Methods = { }, /** - * Form#enable(@form) -> Element + * Form.enable(@form) -> Element * * Enables a fully- or partially-disabled form. **/ @@ -150,7 +150,7 @@ Form.Methods = { }, /** - * Form#findFirstElement(@form) -> Element + * Form.findFirstElement(@form) -> Element * * Finds the first non-hidden, non-disabled control within the form. **/ @@ -168,7 +168,7 @@ Form.Methods = { }, /** - * Form#focusFirstElement(@form) -> Element + * Form.focusFirstElement(@form) -> Element * * Gives keyboard focus to the first element of the form. Returns the form. **/ @@ -179,7 +179,7 @@ Form.Methods = { }, /** - * Form#request([options]) -> Ajax.Request + * Form.request(@form[, options]) -> Ajax.Request * - options (Object): Options to pass along to the `Ajax.Request` * constructor. * @@ -256,7 +256,7 @@ Form.Element = { Form.Element.Methods = { /** - * Form.Element#serialize(@element) -> String + * Form.Element.serialize(@element) -> String * * Returns a URL-encoded string representation of a form control in the * `name=value` format. @@ -275,7 +275,7 @@ Form.Element.Methods = { }, /** alias of: $F - * Form.Element#getValue(@element) -> String | Array + * Form.Element.getValue(@element) -> String | Array * * Returns the current value of a form control. * @@ -291,7 +291,7 @@ Form.Element.Methods = { }, /** - * Form.Element#setValue(@element, value) -> Element + * Form.Element.setValue(@element, value) -> Element * * Sets `value` to be the value of the form control. Returns the element. **/ @@ -303,7 +303,7 @@ Form.Element.Methods = { }, /** - * Form.Element#clear(@element) -> Element + * Form.Element.clear(@element) -> Element * * Clears the contents of a text input. Returns the element. **/ @@ -313,7 +313,7 @@ Form.Element.Methods = { }, /** - * Form.Element#present(@element) -> Element + * Form.Element.present(@element) -> Element * * Returns `true` if a text input has contents, `false` otherwise. **/ @@ -339,7 +339,7 @@ Form.Element.Methods = { }, /** - * Form.Element#disable(@element) -> Element + * Form.Element.disable(@element) -> Element * * Disables a form control, effectively preventing its value from changing * until it is enabled again. @@ -351,7 +351,7 @@ Form.Element.Methods = { }, /** - * Form.Element#enable(@element) -> Element + * Form.Element.enable(@element) -> Element * * Enables a previously disabled form control. **/ diff --git a/src/lang/array.js b/src/lang/array.js index f1634a1..8ab6865 100644 --- a/src/lang/array.js +++ b/src/lang/array.js @@ -37,6 +37,7 @@ Array.from = $A; /** section: Language * class Array + * includes Enumerable * * Prototype extends all native JavaScript arrays with quite a few powerful * methods. diff --git a/src/lang/hash.js b/src/lang/hash.js index 3202594..342c9b9 100644 --- a/src/lang/hash.js +++ b/src/lang/hash.js @@ -13,6 +13,7 @@ function $H(object) { /** section: Language * class Hash + * includes Enumerable * * A set of key/value pairs. *