Permalink
Browse files

doc: Merge/update old Prototype namespace docs into source [#123 stat…

…e:fixed_in_branch]
  • Loading branch information...
1 parent f948220 commit 8a7be689729c963bae784a90989fb02cb8edcb3c @dandean dandean committed with samleb Mar 4, 2010
Showing with 123 additions and 8 deletions.
  1. +0 −7 src/dom.js
  2. +1 −1 src/lang/class.js
  3. +122 −0 src/prototype.js
View
@@ -19,13 +19,6 @@
*
**/
-/** section: DOM
- * Prototype
- *
- * The Prototype namespace.
- *
-**/
-
//= require "dom/dom"
//= require <selector_engine>
//= require "dom/selector"
View
@@ -1,7 +1,7 @@
/* Based on Alex Arnell's inheritance implementation. */
/** section: Language
- * Class
+ * class Class
*
* Manages Prototype's class-based OOP system.
*
View
@@ -6,9 +6,72 @@
*
*--------------------------------------------------------------------------*/
+/** section: Language
+ * Prototype
+ *
+ * The [[Prototype]] namespace provides fundamental information about the
+ * Prototype library you're using, as well as a central repository for default
+ * iterators or functions.
+ *
+ * We say "namespace," because the [[Prototype]] object is not intended for
+ * instantiation, nor for mixing in other objects. It's really just... a
+ * namespace.
+ *
+ * ##### Your version of Prototype
+ *
+ * Your scripts can check against a particular version of Prototype by
+ * examining [[Prototype.Version]], which is a version [[String]] (e.g.
+ * "<%= PROTOTYPE_VERSION %>"). The famous
+ * [script.aculo.us](http://script.aculo.us) library does this at load time to
+ * ensure it's being used with a reasonably recent version of Prototype, for
+ * instance.
+ *
+ * ##### Browser features
+ *
+ * Prototype also provides a (nascent) repository of
+ * [[Prototype.BrowserFeatures browser feature information]], which it then
+ * uses here and there in its source code. The idea is, first, to make
+ * Prototype's source code more readable; and second, to centralize whatever
+ * scripting trickery might be necessary to detect the browser feature, in
+ * order to ease maintenance.
+ *
+ * ##### Default iterators and functions
+ *
+ * Numerous methods in Prototype objects (most notably the [[Enumerable]]
+ * module) let the user pass in a custom iterator, but make it optional by
+ * defaulting to an "identity function" (an iterator that just returns its
+ * argument, untouched). This is the [[Prototype.K]] function, which you'll
+ * see referred to in many places.
+ *
+ * Many methods also take it easy by protecting themselves against missing
+ * methods here and there, reverting to empty functions when a supposedly
+ * available method is missing. Such a function simply ignores its potential
+ * arguments, and does nothing whatsoever (which is, oddly enough,
+ * blazing fast). The quintessential empty function sits, unsurprisingly,
+ * at [[Prototype.emptyFunction]] (note the lowercase first letter).
+**/
var Prototype = {
+
+ /**
+ * Prototype.Version -> String
+ *
+ * The version of the Prototype library you are using (e.g.
+ * "<%= PROTOTYPE_VERSION %>").
+ **/
Version: '<%= PROTOTYPE_VERSION %>',
+ /**
+ * Prototype.Browser
+ *
+ * A collection of [[Boolean]] values indicating the browser which is
+ * currently in use. Available properties are `IE`, `Opera`, `WebKit`,
+ * `MobileSafari` and `Gecko`.
+ *
+ * Example
+ *
+ * Prototype.Browser.WebKit;
+ * //-> true, when executed in any WebKit-based browser.
+ **/
Browser: (function(){
var ua = navigator.userAgent;
// Opera (at least) 8.x+ has "Opera" as a [[Class]] of `window.opera`
@@ -23,9 +86,35 @@ var Prototype = {
}
})(),
+ /**
+ * Prototype.BrowserFeatures
+ *
+ * A collection of [[Boolean]] values indicating the presence of specific
+ * browser features.
+ **/
BrowserFeatures: {
+ /**
+ * Prototype.BrowserFeatures.XPath -> Boolean
+ *
+ * Used internally to detect if the browser supports
+ * [DOM Level 3 XPath](http://www.w3.org/TR/DOM-Level-3-XPath/xpath.html).
+ **/
XPath: !!document.evaluate,
+
+ /**
+ * Prototype.BrowserFeatures.SelectorsAPI -> Boolean
+ *
+ * Used internally to detect if the browser supports the
+ * [NodeSelector API](http://www.w3.org/TR/selectors-api/#nodeselector).
+ **/
SelectorsAPI: !!document.querySelector,
+
+ /**
+ * Prototype.BrowserFeatures.ElementExtensions -> Boolean
+ *
+ * Used internally to detect if the browser supports extending html element
+ * prototypes.
+ **/
ElementExtensions: (function() {
var constructor = window.Element || window.HTMLElement;
return !!(constructor && constructor.prototype);
@@ -52,7 +141,40 @@ var Prototype = {
ScriptFragment: '<script[^>]*>([\\S\\s]*?)<\/script>',
JSONFilter: /^\/\*-secure-([\s\S]*)\*\/\s*$/,
+ /**
+ * Prototype.emptyFunction([argument...]) -> undefined
+ * - argument (Object): Optional arguments
+ *
+ * The [[Prototype.emptyFunction]] does nothing... and returns nothing!
+ *
+ * It is used thoughout the framework to provide a fallback function in order
+ * to cut down on conditionals. Typically you'll find it as a default value
+ * for optional callback functions.
+ **/
emptyFunction: function() { },
+
+ /**
+ * Prototype.K(argument) -> argument
+ * - argument (Object): Optional argument...
+ *
+ * [[Prototype.K]] is Prototype's very own
+ * [identity function](http://en.wikipedia.org/wiki/Identity_function), i.e.
+ * it returns its `argument` untouched.
+ *
+ * This is used throughout the framework, most notably in the [[Enumerable]]
+ * module as a default value for iterators.
+ *
+ * ##### Examples
+ *
+ * Prototype.K('hello world!');
+ * // -> 'hello world!'
+ *
+ * Prototype.K(200);
+ * // -> 200
+ *
+ * Prototype.K(Prototype.K);
+ * // -> Prototype.K
+ **/
K: function(x) { return x }
};

0 comments on commit 8a7be68

Please sign in to comment.