Documenting the idea of extensions better (see #164).

lib/OpenLayers/Events.js

@@ -463,8 +463,46 @@ OpenLayers.Events = OpenLayers.Class({
      * <OpenLayers.Class>, and named after the event they provide.
      * The constructor receives the target <OpenLayers.Events> instance as
      * argument. Extensions should register their browser events using
-     * <register>, with {extension: true} as 4th argument. See
+     * <register>, with {extension: true} as 4th argument. See below for a
-     * <OpenLayers.Events.buttonclick> for a reference implementation.
+     * minimal extension.
+     *
+     * If an extension creates more than one event, an alias for each event
+     * type should be created and reference the same class. The constructor
+     * should set a reference in the target's extensions registry to itself.
+     *
+     * Below is a minimal extension that provides the "foostart" and "fooend"
+     * event types, which replace the native "click" event type if clicked on
+     * an element with the css class "foo":
+     *
+     * (code)
+     *   OpenLayers.Events.foostart = OpenLayers.Class({
+     *       initialize: function(target) {
+     *           this.target = target;
+     *           this.target.register("click", this, this.doStuff, {extension: true});
+     *           // only required if extension provides more than one event type
+     *           this.target.extensions["foostart"] = this;
+     *           this.target.extensions["fooend"] = this;
+     *       },
+     *       destroy: function() {
+     *           this.target.unregister("click", this, this.doStuff);
+     *       },
+     *       doStuff: function(evt) {
+     *           var propagate = true;
+     *           if (OpenLayers.Event.element(evt).className === "foo") {
+     *               propagate = false;
+     *               var target = this.target;
+     *               target.triggerEvent("foostart");
+     *               window.setTimeout(function() {
+     *                   target.triggerEvent("fooend");
+     *               }, 0);
+     *           }
+     *           return propagate;
+     *       }
+     *   });
+     *   // only required if extension provides more than one event type
+     *   OpenLayers.Events.fooend = OpenLayers.Events.foostart;
+     * (end)
+     * 
      */
     extensions: null,