ol.View#fit -- fix docs and add assertions

changelog/upgrade-notes.md

@@ -102,7 +102,7 @@ The replacement of `ol.tilegrid.Zoomify` is a plain `ol.tilegrid.TileGrid`, conf
 
 #### Replace `ol.View.fitExtent()` and `ol.View.fitGeometry()` with `ol.View.fit()`
 * This combines two previously distinct functions into one more flexible call which takes either a geometry or an extent.
-* Rename all calls to `fitExtent` and `fitGeometry` to `fit`
+* Rename all calls to `fitExtent` and `fitGeometry` to `fit`.
 
 #### `ol.tilegrid` changes
 

src/ol/view.js

@@ -436,6 +436,8 @@ ol.View.prototype.getZoom = function() {
 
 /**
  * Fit the given geometry or extent based on the given map size and border.
+ * The size is pixel deminsions of the box to fit the extent into.
+ * In most cases you will want to use the map size, that is `map.getSize()`.
  * Take care on the map angle.
  * @param {ol.geom.SimpleGeometry|ol.Extent} geometry Geometry.
  * @param {ol.Size} size Box pixel size.
@@ -443,8 +445,11 @@ ol.View.prototype.getZoom = function() {
  * @api
  */
 ol.View.prototype.fit = function(geometry, size, opt_options) {
-
   if (!(geometry instanceof ol.geom.SimpleGeometry)) {
+    goog.asserts.assert(goog.isArray(geometry),
+        'invalid extent or geometry');
+    goog.asserts.assert(!ol.extent.isEmpty(geometry),
+        'cannot fit empty extent');
     geometry = ol.geom.Polygon.fromExtent(geometry);
   }
 

test/spec/ol/view.test.js

@@ -480,6 +480,16 @@ describe('ol.View', function() {
       expect(view.getCenter()[0]).to.be(1500);
       expect(view.getCenter()[1]).to.be(1500);
     });
+    it('throws on invalid geometry/extent value', function() {
+      expect(function() {
+        view.fit(true, [200, 200]);
+      }).to.throwException();
+    });
+    it('throws on empty extent', function() {
+      expect(function() {
+        view.fit(ol.extent.createEmpty(), [200, 200]);
+      }).to.throwException();
+    });
   });
 
   describe('centerOn', function() {
@@ -512,5 +522,6 @@ describe('ol.View', function() {
 });
 
 goog.require('ol.View');
+goog.require('ol.extent');
 goog.require('ol.geom.LineString');
 goog.require('ol.geom.Point');