Properly document behavior of set_extent

[kdpenner]

I'm not up-to-date on docstring conventions.

Rationale

Documentation for set_extent is unclear and wrong for one important case.

Implications

Clearer documentation!

[kdpenner]

I'm a little confused by these examples though. I'm not clear why there are 3 cases here. There are only two, with/without crs given?

There's a carve out for a specific condition---a Plate Carree projection with no CRS given and global extent:

https://github.com/SciTools/cartopy/blob/2148e13846944475456390d738b9cbb4391c3add/lib/cartopy/mpl/geoaxes.py#L849-L855

The geodesic for [-180, 180, -90, 90] has no longitudinal extent. If Plate Carree with no CRS given behaved like every other projection, there should be no map. GeoAxes is smart but not smart enough:

>>> ax.set_extent([-180,180,-90,90], p.as_geodetic())
/Users/kpenner/miniconda3/envs/cartopy/lib/python3.7/site-packages/cartopy/mpl/geoaxes.py:834: UserWarning: Attempting to set identical left == right == 180.0 results in singular transformations; automatically expanding.
  self.set_xlim([x1, x2])
>>> ax.get_xlim()
(171.0, 189.0)
>>> ax.get_extent()
(171.0, 180.0, -90.0, 90.0)

Quite the gotcha.

I think the most confusing part is assuming it to be a Geodetic version if no crs is given. So, if I've set up my axes to be Mercator(), I can't call ax.set_extent(ax.get_extent()), it raises an error for me! Maybe this should even be thought about more in the code, not just the docstring?

Yes...this PR is my sneaky way of getting someone (perhaps me) to revisit #131.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}