Marking events.on and events.un as part of the API. Adding examples for both. If this is not the concensus (that these are part of the API) revert this change.

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

lib/OpenLayers/Events.js

@@ -550,16 +550,29 @@ OpenLayers.Events = OpenLayers.Class({
     },
     
     /**
-     * Method: on
+     * APIMethod: on
      * Convenience method for registering listeners with a common scope.
+     *     Internally, this method calls <register> as shown in the examples
+     *     below.
      *
      * Example use:
      * (code)
+     * // register a single listener for the "loadstart" event
+     * events.on({"loadstart", loadStartListener});
+     *
+     * // this is equivalent to the following
+     * events.register("loadstart", undefined, loadStartListener);
+     *
+     * // register multiple listeners to be called with the same `this` object
      * events.on({
      *     "loadstart": loadStartListener,
      *     "loadend": loadEndListener,
      *     scope: object
      * });
+     *
+     * // this is equivalent to the following
+     * events.register("loadstart", object, loadStartListener);
+     * events.register("loadstart", object, loadEndListener);
      * (end)
      */
     on: function(object) {
@@ -641,16 +654,29 @@ OpenLayers.Events = OpenLayers.Class({
     },
     
     /**
-     * Method: un
+     * APIMethod: un
      * Convenience method for unregistering listeners with a common scope.
+     *     Internally, this method calls <unregister> as shown in the examples
+     *     below.
      *
      * Example use:
      * (code)
+     * // unregister a single listener for the "loadstart" event
+     * events.un({"loadstart", loadStartListener});
+     *
+     * // this is equivalent to the following
+     * events.unregister("loadstart", undefined, loadStartListener);
+     *
+     * // unregister multiple listeners with the same `this` object
      * events.un({
      *     "loadstart": loadStartListener,
      *     "loadend": loadEndListener,
      *     scope: object
      * });
+     *
+     * // this is equivalent to the following
+     * events.unregister("loadstart", object, loadStartListener);
+     * events.unregister("loadstart", object, loadEndListener);
      * (end)
      */
     un: function(object) {