Two requests:

* Overlays should have a setVisibility() like they did in v2.
* overlay.setMap() should not be asynchronous, as it makes the layer stacking impossible to maintain.

The upshot of both of these, is that they make it impossible to maintain the stacking order of layers within a map.

The only way to toggle an overlay's visibility seems to be the setMap() method -- layer.setMap(null) then layer.setMap(map). This has a flaw, however: when the layer is added back to the map, it floats to the top of the stack and obscures layers beneath it. In the case of point layers this is minor, but with a polygon overlay the markers beneath cannot be clicked and are visibly obscured by the polygons which are now on top.

Our workaround has been to save a list of all overlays in the preferred stacking order. To toggle a layer's visibility, we iterate over the list of overlays and setMap(null), then iterate again and setMap(map) as appropriate. However, this makes a very unpleasant blinking effect as all overlays are reloaded, and introduces the second issue.

The setMap() method seems to be asynchronous. Iterating over the overlays as above, still does not guarantee that the layers will draw in the preferred order: layers that take longer to load will float to the top of the stack.

Maps API v2 did not have these drawbacks: map.addOverlay() reliably determined the stacking order of the layers, and overlay.show() and overlay.hide() methods did not interfere with stacking order.