Changeset 6982

Timestamp:

01/04/07 15:49:58 (2 years ago)

Author:

alex

Message:

fixing doc style, adding dojo.exists and dojo.getObject, and deprecating what they replace

Location:

trunk/src

Files:

• bootstrap1.js (modified) (12 diffs)
• loader.js (modified) (16 diffs)

trunk/src/bootstrap1.js

@@ -36 +36 @@
 //              'dojo' variable exists.
 // note:
-//              Setting any of these variables *after* the library has loaded does nothing at all.
-// TODOC: is this still true?  Release notes for 0.3 indicated they could be set after load.
-//
+//              Setting any of these variables *after* the library has loaded does
+//              nothing at all.
 
 
@@ -110 +109 @@
 }
 
-dojo.evalProp = function(/*String*/ name, /*Object*/ object, /*Boolean?*/ create){
-        // summary: Returns 'object[name]'.  If not defined and 'create' is true, will return a new Object.
+dojo.getObject = function(/*String*/name, /*Object*/obj, /*Boolean*/create, /*Boolean*/returnWrapper){
+        // summary: 
+        //              gets an object from a dot-separated string, such as "A.B.C"
+        //      description: 
+        //              useful for longer api chains where you have to test each object in
+        //              the chain
+        //      name:   
+        //              Path to an object, in the form "A.B.C".
+        //      obj:
+        //              Optional. Object to use as root of path. Defaults to
+        //              'dojo.global()'. Null may be passed.
+        //      create: 
+        //              Optional. If true, Objects will be created at any point along the
+        //              'path' that is undefined.
+        //      returnWrapper:
+        //              Optional. Returns an object with two properties, 'obj' and 'prop'.
+        //              'obj[prop]' is the reference indicated by 'name'.
+        var tobj, tprop;
+        if(typeof name != "string"){
+                // clearly an error
+                // FIXME: why is this here?
+                return undefined; // Undefined
+        }
+        tobj = obj;
+        if(!tobj){ tobj = dojo.global(); }
+        var parts=name.split("."), i=0, lobj;
+        do{
+                lobj = tobj;
+                tobj = tobj[parts[i++]];
+        }while(i<parts.length && tobj);
+        tprop = tobj;
+        tobj = lobj;
+        return (returnWrapper) ? { obj: tobj, prop: tprop } : tprop; // Object
+}
+
+dojo.exists = function(/*String*/name, /*Object*/obj){
+        // summary: 
+        //              determine if an object supports a given method
+        // description: 
+        //              useful for longer api chains where you have to test each object in
+        //              the chain
+        // name:        
+        //              Path to an object, in the form "A.B.C".
+        // obj:
+        //              Optional. Object to use as root of path. Defaults to
+        //              'dojo.global()'. Null may be passed.
+        if(typeof obj == "string"){
+                // back-compat, should be removed at some point
+                dojo.deprecated("dojo.exists(obj, name)", "use dojo.exists(name, obj, /*optional*/create)", "0.6");
+                // swap them
+                var tmp = name;
+                name = obj;
+                obj = tmp;
+        }
+        return (!!dojo.getObject(name, obj)); // Boolean
+}
+
+dojo.evalProp = function(/*String*/name, /*Object*/object, /*Boolean?*/create){
+        // summary: 
+        //              DEPRECATED. Returns 'object[name]'.  If not defined and 'create' is
+        //              true, will return a new Object.
         // description:
         //              Returns null if 'object[name]' is not defined and 'create' is not true.
         //              Note: 'defined' and 'exists' are not the same concept.
-        if((!object)||(!name)){ return undefined; }// undefined
-        if(!dj_undef(name, object)){ return object[name]; }// mixed
-        return (create ? (object[name]={}) : undefined);        // mixed
+        dojo.deprecated("dojo.evalProp", "just use hash syntax. Sheesh.", "0.6");
+        return object[name] || (create ? (object[name]={}) : undefined);        // mixed
 }
 
 dojo.parseObjPath = function(/*String*/ path, /*Object?*/ context, /*Boolean?*/ create){
-        // summary: Parse string path to an object, and return corresponding object reference and property name.
+        // summary: 
+        //              DEPRECATED. Parse string path to an object, and return
+        //              corresponding object reference and property name.
         // description:
         //              Returns an object with two properties, 'obj' and 'prop'.
@@ -127 +186 @@
         // path: Path to an object, in the form "A.B.C".
         // context: Object to use as root of path.  Defaults to 'dojo.global()'.
-        // create: If true, Objects will be created at any point along the 'path' that is undefined.
-        var object = (context || dojo.global());
-        var names = path.split('.');
-        var prop = names.pop();
-        for(var i=0,l=names.length;i<l && object;i++){
-                object = dojo.evalProp(names[i], object, create);
-        }
-        return {obj: object, prop: prop};       // Object: {obj: Object, prop: String}
+        // create: 
+        //              If true, Objects will be created at any point along the 'path' that
+        //              is undefined.
+        dojo.deprecated("dojo.parseObjPath", "use dojo.getObject(path, context, create, true)", "0.6");
+        return dojo.getObject(path, context, create, true); // Object: {obj: Object, prop: String}
 }
 
 dojo.evalObjPath = function(/*String*/ path, /*Boolean?*/ create){
-        // summary: Return the value of object at 'path' in the global scope, without using 'eval()'.
+        // summary: 
+        //              DEPRECATED. Return the value of object at 'path' in the global
+        //              scope, without using 'eval()'.
         // path: Path to an object, in the form "A.B.C".
-        // create: If true, Objects will be created at any point along the 'path' that is undefined.
-        if(typeof path != "string"){
-                return dojo.global();
-        }
-        // fast path for no periods
-        if(path.indexOf('.') == -1){
-                return dojo.evalProp(path, dojo.global(), create);              // mixed
-        }
-
-        //MOW: old 'with' syntax was confusing and would throw an error if parseObjPath returned null.
-        var ref = dojo.parseObjPath(path, dojo.global(), create);
-        if(ref){
-                return dojo.evalProp(ref.prop, ref.obj, create);        // mixed
-        }
-        return null;
+        // create: 
+        //              If true, Objects will be created at any point along the 'path' that
+        //              is undefined.
+        dojo.deprecated("dojo.evalObjPath", "use dojo.getObject(path, null, create)", "0.6");
+        return dojo.getObject(path, null, create); // Object
 }
 
@@ -162 +210 @@
         // TODO: overriding Error.prototype.toString won't accomplish this?
         //              ... since natively generated Error objects do not always reflect such things?
+        /*
         if(!dj_undef("message", exception)){
                 return exception.message;               // String
@@ -169 +218 @@
                 return exception;                               // Error
         }
+        */
+        return (exception["message"]||exception["description"]||exception);
 }
 
 dojo.raise = function(/*String*/ message, /*Error?*/ exception){
-        // summary: Common point for raising exceptions in Dojo to enable logging.
-        //      Throws an error message with text of 'exception' if provided, or
-        //      rethrows exception object.
+        // summary:
+        //              Common point for raising exceptions in Dojo to enable logging.
+        //              Throws an error message with text of 'exception' if provided, or
+        //              rethrows exception object.
 
         if(exception){
@@ -204 +256 @@
 
 function dj_eval(/*String*/ scriptFragment){
-        // summary: Perform an evaluation in the global scope.  Use this rather than calling 'eval()' directly.
-        // description: Placed in a separate function to minimize size of trapped evaluation context.
+        // summary: 
+        //              Perform an evaluation in the global scope.  Use this rather than
+        //              calling 'eval()' directly.
+        // description: 
+        //              Placed in a separate function to minimize size of trapped
+        //              evaluation context.
         // note:
         //       - JSC eval() takes an optional second argument which can be 'unsafe'.
@@ -222 +278 @@
 
 dojo.deprecated = function(/*String*/ behaviour, /*String?*/ extra, /*String?*/ removal){
-        // summary: Log a debug message to indicate that a behavior has been deprecated.
+        // summary: 
+        //              Log a debug message to indicate that a behavior has been
+        //              deprecated.
         // extra: Text to append to the message.
-        // removal: Text to indicate when in the future the behavior will be removed.
+        // removal: 
+        //              Text to indicate when in the future the behavior will be removed.
         var message = "DEPRECATED: " + behaviour;
         if(extra){ message += " " + extra; }
@@ -232 +291 @@
 
 dojo.render = (function(){
-        //TODOC: HOW TO DOC THIS?
-        // summary: Details rendering support, OS and browser of the current environment.
-        // TODOC: is this something many folks will interact with?  If so, we should doc the structure created...
+        //      summary: 
+        //              Builds the dojo.render object which details rendering support, OS
+        //              and browser of the current environment.
+        //      description:
+        //              commonly used properties of dojo.render (in HTML environments)
+        //              include:
+        //
+        //                      dojo.render.html.ie
+        //                      dojo.render.html.opera
+        //                      dojo.render.html.khtml
+        //                      dojo.render.html.safari
+        //                      dojo.render.html.moz
+        //                      dojo.render.html.mozilla
+        //
+        //              additional objects are provided to detail support for other types
+        //              of media and environments. For instance, the following determines
+        //              if there's native SVG support in a browser:
+        //                      
+        //                      if(dojo.render.svg.capable && dojo.render.svg.builtin){
+        //                              ...
+        //                      }
+        //
+        //              Other properties of note:
+        //
+        //                      dojo.render.os.win
+        //                      dojo.render.os.osx
+        //                      dojo.render.os.linux
+        //                      dojo.render.html.UA (navigator.userAgent)
+        //                      dojo.render.html.AV (navigator.appVersion)
+        //                      dojo.render.html.ie50 (MSIE 5.0)
+        //                      dojo.render.html.ie55 (MSIE 5.5)
+        //                      dojo.render.html.ie60 (MSIE 6.0)
+        //                      dojo.render.html.ie70 (MSIE 7.0)
+        //
+        //              All reasonable measures are taken to ensure that the values in
+        //              dojo.render represent the real environment and not, say, a browser
+        //              "masquerading" as a different browser version. Only supported
+        //              environments and browsers will likely have entires in dojo.render.
         function vscaffold(prefs, names){
                 var tmp = {
@@ -276 +370 @@
 dojo.hostenv = (function(){
         // TODOC:  HOW TO DOC THIS?
-        // summary: Provides encapsulation of behavior that changes across different 'host environments'
-        //                      (different browsers, server via Rhino, etc).
-        // description: None of these methods should ever be called directly by library users.
-        //                              Use public methods such as 'loadModule' instead.
+        // summary: 
+        //              Provides encapsulation of behavior that changes across different
+        //              'host environments' (different browsers, server via Rhino, etc).
+        // description: 
+        //              None of these methods should ever be called directly by library
+        //              users.  Use public methods such as 'loadModule' instead.
 
         // default configuration options
@@ -323 +419 @@
 
                 getText: function(/*String*/ uri){
-                        // summary:     Read the plain/text contents at the specified 'uri'.
-                        // description:
-                        //                      If 'getText()' is not implemented, then it is necessary to override
-                        //                      'loadUri()' with an implementation that doesn't rely on it.
-
+                        //      summary:        
+                        //              Read the plain/text contents at the specified 'uri'.
+                        //      description:
+                        //              If 'getText()' is not implemented, then it is necessary to
+                        //              override 'loadUri()' with an implementation that doesn't
+                        //              rely on it.
                         dojo.unimplemented('getText', "uri=" + uri);
                 }
@@ -335 +432 @@
 
 dojo.hostenv.getBaseScriptUri = function(){
-        // summary: Return the base script uri that other scripts are found relative to.
-        // TODOC: HUH?  This comment means nothing to me.  What other scripts? Is this the path to other dojo libraries?
+        // summary: 
+        //              Return the base script uri that other scripts are found relative to.
         //              MAYBE:  Return the base uri to scripts in the dojo library.      ???
         // return: Empty string or a path ending in '/'.
+
+
+        // TODOC: 
+        //              HUH? This comment means nothing to me. What other scripts? Is
+        //              this the path to other dojo libraries?
         if(djConfig.baseScriptUri.length){
                 return djConfig.baseScriptUri;
@@ -350 +452 @@
                 dojo.raise("Nothing returned by getLibraryScriptUri(): " + uri);
         }
-
-        // MOW: uri seems to not be actually used.  Seems to be hard-coding to djConfig.baseRelativePath... ???
-        var lastslash = uri.lastIndexOf('/');           // MOW ???
+        // MOW: 
+        //              uri seems to not be actually used.  Seems to be hard-coding to
+        //              djConfig.baseRelativePath... ???
+
         djConfig.baseScriptUri = djConfig.baseRelativePath;
         return djConfig.baseScriptUri;  // String
 }
+// vim:ai:ts=4:noet:textwidth=80

trunk/src/loader.js

@@ -49 +49 @@
                 loadedUris: [],
         
-                //WARNING: This variable is referenced by packages outside of bootstrap: FloatingPane.js and undo/browser.js
+                //WARNING: 
+                //              This variable is referenced by packages outside of bootstrap:
+                //              FloatingPane.js and undo/browser.js
                 post_load_: false,
                 
@@ -65 +67 @@
 
 dojo.hostenv.loadPath = function(/*String*/relpath, /*String?*/module, /*Function?*/cb){
-// summary:
-//      Load a Javascript module given a relative path
-//
-// description:
-//      Loads and interprets the script located at relpath, which is relative to the
-//      script root directory.  If the script is found but its interpretation causes
-//      a runtime exception, that exception is not caught by us, so the caller will
-//      see it.  We return a true value if and only if the script is found.
-//
-//      For now, we do not have an implementation of a true search path.  We
-//      consider only the single base script uri, as returned by getBaseScriptUri().
-//
-// relpath: A relative path to a script (no leading '/', and typically
-//      ending in '.js').
-// module: A module whose existance to check for after loading a path.
-//      Can be used to determine success or failure of the load.
-// cb: a callback function to pass the result of evaluating the script
+        //      summary:
+        //              Load a Javascript module given a relative path
+        //
+        //      description:
+        //              Loads and interprets the script located at relpath, which is
+        //              relative to the script root directory.  If the script is found but
+        //              its interpretation causes a runtime exception, that exception is
+        //              not caught by us, so the caller will see it.  We return a true
+        //              value if and only if the script is found.
+        //
+        //              For now, we do not have an implementation of a true search path.
+        //              We consider only the single base script uri, as returned by
+        //              getBaseScriptUri().
+        //
+        // relpath: 
+        //              A relative path to a script (no leading '/', and typically ending
+        //              in '.js').
+        // module: 
+        //              A module whose existance to check for after loading a path.  Can be
+        //              used to determine success or failure of the load.
+        // cb: 
+        //              a callback function to pass the result of evaluating the script
 
         var uri;
@@ -102 +109 @@
 
 dojo.hostenv.loadUri = function(/*String (URL)*/uri, /*Function?*/cb){
-// summary:
-//      Loads JavaScript from a URI
-//
-// description:
-//      Reads the contents of the URI, and evaluates the contents.  This is used to load modules as well
-//      as resource bundles.  Returns true if it succeeded. Returns false if the URI reading failed.
-//      Throws if the evaluation throws.
-//
-// uri: a uri which points at the script to be loaded
-// cb: a callback function to process the result of evaluating the script as an expression, typically
-//      used by the resource bundle loader to load JSON-style resources
+        //      summary:
+        //              Loads JavaScript from a URI
+        //      description:
+        //              Reads the contents of the URI, and evaluates the contents.  This is
+        //              used to load modules as well as resource bundles. Returns true if
+        //              it succeeded. Returns false if the URI reading failed.  Throws if
+        //              the evaluation throws.
+        //      uri: a uri which points at the script to be loaded
+        //      cb: 
+        //              a callback function to process the result of evaluating the script
+        //              as an expression, typically used by the resource bundle loader to
+        //              load JSON-style resources
 
         if(this.loadedUris[uri]){
@@ -196 +204 @@
 
 dojo.addOnUnload = function(/*Object?*/obj, /*String|Function?*/functionName){
-// summary: registers a function to be triggered when the page unloads
-//
-// usage:
-//      dojo.addOnLoad(functionPointer)
-//      dojo.addOnLoad(object, "functionName")
+        // summary: registers a function to be triggered when the page unloads
+        // usage:
+        //              dojo.addOnLoad(functionPointer)
+        //              dojo.addOnLoad(object, "functionName")
         var dh = dojo.hostenv;
         if(arguments.length == 1){
@@ -231 +238 @@
 
 dojo.hostenv.getModuleSymbols = function(/*String*/modulename){
-// summary:
-//      Converts a module name in dotted JS notation to an array representing the path in the source tree
+        // summary:
+        //              Converts a module name in dotted JS notation to an array
+        //              representing the path in the source tree
         var syms = modulename.split(".");
         for(var i = syms.length; i>0; i--){
@@ -251 +259 @@
 
 dojo.hostenv._global_omit_module_check = false;
-dojo.hostenv.loadModule = function(/*String*/moduleName, /*Boolean?*/exactOnly, /*Boolean?*/omitModuleCheck){
-// summary:
-//      loads a Javascript module from the appropriate URI
-//
-// description:
-//      loadModule("A.B") first checks to see if symbol A.B is defined. 
-//      If it is, it is simply returned (nothing to do).
-//      
-//      If it is not defined, it will look for "A/B.js" in the script root directory,
-//      followed by "A.js".
-//      
-//      It throws if it cannot find a file to load, or if the symbol A.B is not
-//      defined after loading.
-//      
-//      It returns the object A.B.
-//      
-//      This does nothing about importing symbols into the current package.
-//      It is presumed that the caller will take care of that. For example, to import
-//      all symbols:
-//      
-//         with (dojo.hostenv.loadModule("A.B")) {
-//            ...
-//         }
-//      
-//      And to import just the leaf symbol:
-//      
-//         var B = dojo.hostenv.loadModule("A.B");
-//         ...
-//      
-//      dj_load is an alias for dojo.hostenv.loadModule
+
+dojo.hostenv.loadModule = function(     /*String*/moduleName, 
+                                                                        /*Boolean?*/exactOnly, 
+                                                                        /*Boolean?*/omitModuleCheck){
+        //      summary:
+        //              loads a Javascript module from the appropriate URI
+        //      description:
+        //              loadModule("A.B") first checks to see if symbol A.B is defined. If
+        //              it is, it is simply returned (nothing to do).
+        //      
+        //              If it is not defined, it will look for "A/B.js" in the script root
+        //              directory, followed by "A.js".
+        //      
+        //              It throws if it cannot find a file to load, or if the symbol A.B is
+        //              not defined after loading.
+        //      
+        //              It returns the object A.B.
+        //      
+        //              This does nothing about importing symbols into the current package.
+        //              It is presumed that the caller will take care of that. For example,
+        //              to import all symbols:
+        //      
+        //                      with (dojo.hostenv.loadModule("A.B")) {
+        //                              ...
+        //                      }
+        //      
+        //              And to import just the leaf symbol:
+        //      
+        //                      var B = dojo.hostenv.loadModule("A.B");
+        //                      ...
+        //      
+        //              dj_load is an alias for dojo.hostenv.loadModule
 
         if(!moduleName){ return; }
@@ -368 +378 @@
 
 dojo.hostenv.startPackage = function(/*String*/packageName){
-// summary:
-//      Creates a JavaScript package
-//
-// description:
-//      startPackage("A.B") follows the path, and at each level creates a new empty
-//      object or uses what already exists. It returns the result.
-//
-// packageName: the package to be created as a String in dot notation
+        // summary:
+        //              Creates a JavaScript package
+        // description:
+        //              startPackage("A.B") follows the path, and at each level creates a
+        //              new empty object or uses what already exists. It returns the
+        //              result.
+        // packageName: 
+        //              the package to be created as a String in dot notation
 
         //Make sure we have a string.
@@ -394 +404 @@
 
 dojo.hostenv.findModule = function(/*String*/moduleName, /*Boolean?*/mustExist){
-// summary:
-//      Returns the Object representing the module, if it exists, otherwise null.
-//
-// moduleName A fully qualified module including package name, like 'A.B'.
-// mustExist Optional, default false. throw instead of returning null
-//      if the module does not currently exist.
+        //      summary:
+        //              Returns the Object representing the module, if it exists, otherwise
+        //              null.
+        //      moduleName: 
+        //              A fully qualified module including package name, like 'A.B'.
+        //      mustExist: 
+        //              Optional, default false. throw instead of returning null if the
+        //              module does not currently exist.
 
         var lmn = String(moduleName);
@@ -416 +428 @@
 
 dojo.kwCompoundRequire = function(/*Object containing Arrays*/modMap){
-// description:
-//      This method taks a "map" of arrays which one can use to optionally load dojo
-//      modules. The map is indexed by the possible dojo.hostenv.name_ values, with
-//      two additional values: "default" and "common". The items in the "default"
-//      array will be loaded if none of the other items have been choosen based on
-//      the hostenv.name_ item. The items in the "common" array will _always_ be
-//      loaded, regardless of which list is chosen.  Here's how it's normally
-//      called:
-//      
-//      dojo.kwCompoundRequire({
-//              browser: [
-//                      ["foo.bar.baz", true, true], // an example that passes multiple args to loadModule()
-//                      "foo.sample.*",
-//                      "foo.test,
-//              ],
-//              default: [ "foo.sample.*" ],
-//              common: [ "really.important.module.*" ]
-//      });
+        //      description:
+        //              This method taks a "map" of arrays which one can use to optionally
+        //              load dojo modules. The map is indexed by the possible
+        //              dojo.hostenv.name_ values, with two additional values: "default"
+        //              and "common". The items in the "default" array will be loaded if
+        //              none of the other items have been choosen based on the
+        //              hostenv.name_ item. The items in the "common" array will _always_
+        //              be loaded, regardless of which list is chosen.  Here's how it's
+        //              normally called:
+        //      
+        //                      dojo.kwCompoundRequire({
+        //                              // an example that passes multiple args to loadModule()
+        //                              browser: [
+        //                                      ["foo.bar.baz", true, true], 
+        //                                      "foo.sample.*",
+        //                                      "foo.test,
+        //                              ],
+        //                              default: [ "foo.sample.*" ],
+        //                              common: [ "really.important.module.*" ]
+        //                      });
 
         var common = modMap["common"]||[];
@@ -449 +463 @@
 
 dojo.require = function(/*String*/ resourceName){
-        // summary
-        //      Ensure that the given resource (ie, javascript
-        //      source file) has been loaded.
-        // description
-        //      dojo.require() is similar to C's #include command or java's "import" command.
-        //      You call dojo.require() to pull in the resources (ie, javascript source files)
-        //      that define the functions you are using. 
+        //      summary:
+        //              Ensure that the given resource (ie, javascript source file) has
+        //              been loaded.
+        //      description:
+        //              dojo.require() is similar to C's #include command or java's
+        //              "import" command. You call dojo.require() to pull in the resources
+        //              (ie, javascript source files) that define the functions you are
+        //              using. 
         //
-        //      Note that in the case of a build, many resources have already been included
-        //      into dojo.js (ie, many of the javascript source files have been compressed and
-        //      concatened into dojo.js), so many dojo.require() calls will simply return
-        //      without downloading anything.
+        //              Note that in the case of a build, many resources have already been
+        //              included into dojo.js (ie, many of the javascript source files have
+        //              been compressed and concatened into dojo.js), so many