With this change, the generic 'change' event is properly documented, as
all other events. It is no longer necessary to annotate `@fires change` for
every ol.Observable subclass.
This commit changes the signature of ol.layer.Group#getLayers from {ol.Collection.<ol.layer.Base>|undefined} to {!ol.Collection.<ol.layer.Base>}. In this way the caller is guaranteed that getLayers returns a dereferencable object.
The map does not fire ol.render.Event#render. Change events are
now only listed for classes that fire them, and a description
about when they are fired is added.
We no longer add observable annotations to the constructor.
Instead, we just mark getters (and for read/write properties
also setters) with an observable annotation.
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.
This commit simplifies the exports.js plugin so it only relies
on the stability notes to generate the documentation, which
completely decouples it from the exportable API.
As a rule of thumb, whenever something has an 'api' annotation,
it should also have a 'stability' annotation. A more verbose
documentation of ol3 specific annotation usage is available in
the new 'apidoc/readme.md' file.
This commit also modifies all source files to implement these
usage suggestions.
Add `ol.ObjectEvent` for changes to `ol.Object` properties. Previously, `ol.Object` dispatched instances of `goog.events.Event` with type `change`. Now `ol.ObjectEvent` instances will be dispatched on property changes. The events include a `getKey` method to get the name of the property being changed. The `beforepropertychange` type event is fired before a property value changes, and the `propertychange` type event fires after the property value changes.
Where an enum value is used as an event type, it should be alllowercase (to follow DOM events). Property names should be ALLUPPERCASE in this case (just as camelCase and PascalCase are converted to CONSTANT_CASE).
Any event target can be used to dispatch generic goog.events.Event instances with an arbitrary type. In cases where we dispatch custom events, we should not use type values that collide with those used for generic events (at least internally). This allows listeners a better chance of knowing what kind of argument they will receive.
As subsequent change will clean up the enumeration and add a bit more consistency.
This PR adds documentation for observable properties, which will then be pulled into the docs correctly once #1180 is merged. This is a first pass based on searching for definition of observable properties being defined as enums after lines ending with `Property = {`. If there are observable properties implemented that don't follow this pattern then they are not included.
I've added simple descriptions based on what I know or could easily figure out, there may be some properties (like preload) that are not correctly described.
I've also added `readonly` annotations where I knew that a property was readonly. I may have missed some readonly properties.
ol.layer.Base has a bunch of properties but I don't think it is exported so the documentation of these properties will not show up, so I added the documentation to ol.layer.Layer instead even though this isn't really where it should be documented.
Layer renderers should not be responsible for listening to layer
properties change and triggering a render.
Layer change events are now forwarded to the map which will trigger a render.
