Files

Andreas Hocevar fbdbbfb7a7 Get rid of stability annotations and document stability with api

This change adds a stability value to the api annotation, with
'experimental' as default value.

enum, typedef and event annotations are never exportable, but
api annotations are needed there to make them appear in the
docs.

Nested typedefs are no longer inlined recursively, because the
resulting tables get too wide with the current template.

2014-04-29 09:53:07 -06:00

2.8 KiB

Raw Blame History

Externs

This directory contains externs files, which tell the Closure compiler about symbols and properties that it should not rename.

oli.js and olx.js

These two files are special externs that belong to ol3, and this document explains their purpose and how they are used.

Prevent class properties from being renamed

For events, we make properties available to the application. Other than methods, which can be made available by just marking them with the @api annotation, properties are exported using oli.js:

/** @interface */
oli.MapBrowserEvent;

/**
 * @type {ol.Coordinate}
 * @todo api
 */
oli.MapBrowserEvent.prototype.coordinate;

In the source file (src/ol/MapBrowserEvent.js), the class needs to implement this interface:

/**
 * ...
 * @constructor
 * @implements {oli.MapBrowserEvent}
 */
ol.MapBrowserEvent = function(type, map, browserEvent, opt_frameState) {

  // ...

  /**
   * @type {ol.Coordinate}
   */
  this.coordinate = map.getEventCoordinate(this.originalEvent);

  // ...

};

Override methods in custom classes

For custom subclasses in applications, which can be created using ol.extends, the API may want to make certain methods available to override. In addition to marking such methods as @api, they need also be added to an interface in oli.js:

/**
 * @interface
 */
oli.control.Control;

/**
 * @param {ol.Map} map Map.
 * @return {undefined} Undefined.
 */
oli.control.Control.prototype.setMap = function(map) {};

This interface must be implemented by the class in the source file (src/ol/control/control.js):

/**
 * ...
 * @constructor
 * @implements {oli.control.Control}
 */
ol.control.Control = function(options) {
  // ...
};

// ...

/**
 * Application subclasses may override this.
 * @param {ol.Map} map Map.
 * @todo api
 */
ol.control.Control.prototype.setMap = function(map) {
  // ...
};

Export object literals

Object literals cannot be exported like classes. To make sure that their properties do not get renamed, they go in olx.js:

/**
 * @typedef {{element: (Element|undefined),
 *     target: (Element|string|undefined)}}
 * @todo api
 */
olx.control.ControlOptions;

/**
 * The element is the control's container element. This only needs to be
 * specified if you're developing a custom control.
 * @type {Element|undefined}
 */
olx.control.ControlOptions.prototype.element;

/**
 * Specify a target if you want the control to be rendered outside of the map's
 * viewport.
 * @type {Element|string|undefined}
 */
olx.control.ControlOptions.prototype.target;

In the source code, the name used for the typedef is used as type whenever this object literal is expected:

/**
 * ...
 * @param {olx.control.ControlOptions} options Control options.
 */
ol.control.Control = function(options) {
  // ...
};

2.8 KiB Raw Blame History