openlayers/ol3 — pull request #2609 by elemoine (2014-08-25 07:52:09+00:00)
Title: Annotate stable view functions and options

This PR adds `@api stable` annotations to `ol.View` and `olx.ViewOptions`.

Things that I've left as "experimental":

- The `constrainCenter`, `constrainResolution`, `constrainRotation` methods. More generally, I've considered that the constraints system is not stable, because we can make it more convenient and consistent.

- The `calculateExtent`, `fitExtent`, `getResolutionForExtent`, `fitGeometry`, `centerOn` methods. These methods have in common that they take a `size` (box pixel size) as an argument. I'm personally happy with these methods, but people have been complaining about them.

`calculateExtent` and `fitExtent` are so useful to people that we could decide to mark them as "stable" for the release. I'm happy with that. Please give your opinion.

- The `constrainRotation` and `enableRotation` options. I left those as "experimental" because I think they're not very consistent with the options for constraining the resolution and the extent. I'm a bit conservative here.

- The `extent` option. This is the option for constraining the center, in a way that it cannot be outside the provided extent. I think we should make the "center constraint" system more flexible. See [this discussion](https://groups.google.com/d/msg/ol3-dev/LoBb9VACPfI/c1uuh4lHz9UJ) on the mailing list for example.

Please review.