#764 - add documentation for OpenLayers.Console methods

git-svn-id: http://svn.openlayers.org/trunk/openlayers@3327 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf

lib/OpenLayers/Console.js

@@ -8,21 +8,190 @@
  * calls to OpenLayers.Console methods will get redirected to window.console.
  * This makes use of the Firebug extension where available and allows for
  * cross-browser debugging Firebug style.
+ *
+ * Note that behavior will differ with the Firebug extention and Firebug Lite.
+ * Most notably, the Firebug Lite console does not currently allow for
+ * hyperlinks to code or for clicking on object to explore their properties.
+ * 
+ * @fileoverview Error logging and debugging console
  */
-OpenLayers.Console = {};
-(function() {
+OpenLayers.Console = {
     /**
      * Create empty functions for all console methods.  The real value of these
      * properties will be set if Firebug Lite (../Firebug/firebug.js script) is
      * included.  We explicitly require the Firebug Lite script to trigger
      * functionality of the OpenLayers.Console methods.
      */
-    var methods = ['log', 'debug', 'info', 'warn', 'error', 'assert',
-                   'dir', 'dirxml', 'trace', 'group', 'groupEnd', 'time',
-                   'timeEnd', 'profile', 'profileEnd', 'count'];
-    for(var i=0; i<methods.length; ++i) {
-        OpenLayers.Console[methods[i]] = function() {};
-    }
+    
+    /**
+     * Log an object in the console.  The Firebug Lite console logs string
+     * representation of objects.  Given multiple arguments, they will
+     * be cast to strings and logged with a space delimiter.  If the first
+     * argument is a string with printf-like formatting, subsequent arguments
+     * will be used in string substitution.  Any additional arguments (beyond
+     * the number substituted in a format string) will be appended in a space-
+     * delimited line.
+     *
+     * Examples:
+     * // Firebug Lite logs someObject.toString()
+     * OpenLayers.Console.log(someObject);
+     * 
+     * // string substitution
+     * OpenLayers.Console.log("%s jumped over %s", cow, moon);
+     * 
+     * @param {Object} object
+     */
+    log: function() {},
+
+    /**
+     * Writes a message to the console, including a hyperlink to the line
+     * where it was called.
+     *
+     * May be called with multiple arguments as with OpenLayers.Console.log().
+     * 
+     * @param (Object) object
+     */
+    debug: function() {},
+
+    /**
+     * Writes a message to the console with the visual "info" icon and color
+     * coding and a hyperlink to the line where it was called.
+     *
+     * May be called with multiple arguments as with OpenLayers.Console.log().
+     * 
+     * @param (Object) object
+     */
+    info: function() {},
+
+    /**
+     * Writes a message to the console with the visual "warning" icon and
+     * color coding and a hyperlink to the line where it was called.
+     *
+     * May be called with multiple arguments as with OpenLayers.Console.log().
+     * 
+     * @param (Object) object
+     */
+    warn: function() {},
+
+    /**
+     * Writes a message to the console with the visual "error" icon and color
+     * coding and a hyperlink to the line where it was called.
+     *
+     * May be called with multiple arguments as with OpenLayers.Console.log().
+     * 
+     * @param (Object) object
+     */
+    error: function() {},
+
+    /**
+     * Tests that an expression is true. If not, it will write a message to
+     * the console and throw an exception.
+     *
+     * May be called with multiple arguments as with OpenLayers.Console.log().
+     * 
+     * @param (Object) expression
+     */
+    assert: function() {},
+
+    /**
+     * Prints an interactive listing of all properties of the object. This
+     * looks identical to the view that you would see in the DOM tab.
+     * 
+     * @param (Object) object
+     */
+    dir: function() {},
+
+    /**
+     * Prints the XML source tree of an HTML or XML element. This looks
+     * identical to the view that you would see in the HTML tab. You can click
+     * on any node to inspect it in the HTML tab.
+     * 
+     * @param (Object) object
+     */
+    dirxml: function() {},
+
+    /**
+     * Prints an interactive stack trace of JavaScript execution at the point
+     * where it is called.  The stack trace details the functions on the stack,
+     * as well as the values that were passed as arguments to each function.
+     * You can click each function to take you to its source in the Script tab,
+     * and click each argument value to inspect it in the DOM or HTML tabs.
+     * 
+     */
+    trace: function() {},
+
+    /**
+     * Writes a message to the console and opens a nested block to indent all
+     * future messages sent to the console. Call OpenLayers.Console.groupEnd()
+     * to close the block.
+     *
+     * May be called with multiple arguments as with OpenLayers.Console.log().
+     * 
+     * @param (Object) object
+     */
+    group: function() {},
+
+    /**
+     * Closes the most recently opened block created by a call to
+     * OpenLayers.Console.group
+     */
+    groupEnd: function() {},
+    
+    /**
+     * Creates a new timer under the given name. Call
+     * OpenLayers.Console.timeEnd(name)
+     * with the same name to stop the timer and print the time elapsed.
+     *
+     * @param {String} name
+     */
+    time: function() {},
+
+    /**
+     * Stops a timer created by a call to OpenLayers.Console.time(name) and
+     * writes the time elapsed.
+     *
+     * @param {String} name
+     */
+    timeEnd: function() {},
+
+    /**
+     * Turns on the JavaScript profiler. The optional argument title would
+     * contain the text to be printed in the header of the profile report.
+     *
+     * This function is not currently implemented in Firebug Lite.
+     * 
+     * @param {String} title Optional title for the profiler
+     */
+    profile: function() {},
+
+    /**
+     * Turns off the JavaScript profiler and prints its report.
+     * 
+     * This function is not currently implemented in Firebug Lite.
+     */
+    profileEnd: function() {},
+
+    /**
+     * Writes the number of times that the line of code where count was called
+     * was executed. The optional argument title will print a message in
+     * addition to the number of the count.
+     *
+     * This function is not currently implemented in Firebug Lite.
+     *
+     * @param {String} title Optional title to be printed with count
+     */
+    count: function() {},
+
+    /** @final @type String */
+    CLASS_NAME: "OpenLayers.Console"
+};
+
+/**
+ * Execute an anonymous function to extend the OpenLayers.Console namespace
+ * if the firebug.js script is included.  This closure is used so that the
+ * "scripts" and "i" variables don't pollute the global namespace.
+ */
+(function() {
     /**
      * If Firebug Lite is included (before this script), re-route all
      * OpenLayers.Console calls to the console object.