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.
Since we do not use the 'along' property anywhere, and the
resulting array returned by closestOnSegment could cause trouble
when working with 3d coodinates, now only the closest point is
returned, and the squared distance to the segment is calculated
by squaredDistanceToSegment instead.
In the typical sequence of parse-transform-render the most efficient place to transform coordinate values is deep within the parser immediately after values have been read (this would avoid a second pass over whatever structure is used to back geometries). To accomplish this transform during parsing, we could add back parser read options to pass the transform function around.
Until then, a transform method on geometries is straightforward to implement. This means we do a second pass through coordinate structures to transform, but this is typically done only once immediately after parsing.
