Merge pull request #2399 from tschaub/functions

Annotate functions that are aliases for goog functions.

src/ol/events/condition.js

@@ -50,6 +50,7 @@ ol.events.condition.altShiftKeysOnly = function(mapBrowserEvent) {
  * Always true.
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} True.
+ * @function
  * @api
  */
 ol.events.condition.always = goog.functions.TRUE;
@@ -79,6 +80,7 @@ ol.events.condition.mouseMove = function(mapBrowserEvent) {
  * Always false.
  * @param {ol.MapBrowserEvent} mapBrowserEvent Map browser event.
  * @return {boolean} False.
+ * @function
  * @api
  */
 ol.events.condition.never = goog.functions.FALSE;

src/ol/ol.js

@@ -208,14 +208,34 @@ ol.ZOOMSLIDER_ANIMATION_DURATION = 200;
 
 
 /**
- * ol.inherits is an alias to the goog.inherits function. It is exported
- * for use in non-compiled application code.
+ * Inherit the prototype methods from one constructor into another.
  *
- * FIXME: We use a new line to fake the linter. Without the new line the
- * linter complains with:
+ * Usage:
  *
- * "Missing newline between constructor and goog.inherits"
+ *     function ParentClass(a, b) { }
+ *     ParentClass.prototype.foo = function(a) { }
+ *
+ *     function ChildClass(a, b, c) {
+ *       goog.base(this, a, b);
+ *     }
+ *     ol.inherits(ChildClass, ParentClass);
+ *
+ *     var child = new ChildClass('a', 'b', 'see');
+ *     child.foo(); // This works.
+ *
+ * In addition, a superclass' implementation of a method can be invoked as
+ * follows:
+ *
+ *     ChildClass.prototype.foo = function(a) {
+ *       ChildClass.superClass_.foo.call(this, a);
+ *       // Other code here.
+ *     };
+ *
+ * @param {Function} childCtor Child constructor.
+ * @param {Function} parentCtor Parent constructor.
+ * @function
  * @api
  */
 ol.inherits =
     goog.inherits;
+// note that the newline above is necessary to satisfy the linter