Open Radar

 
Summary:

1. Doc of CALayer.sublayers
The sublayers are listed in back to front order.

2. Doc of CALayer.zPosition:
Changing the value of this property changes the the front-to-back ordering of layers onscreen. Higher values place this layer visually closer to the viewer than layers with lower values.

3. Doc CALayer.addSublayer(:):
Appends the layer to the layer’s list of sublayers.

The "back to front order" and "front-to-back ordering" should be the same thing. But in reality, the order of the value of sublayers may be different from the ordering determined by zPosition, thus causes inconsistency. For example, one can call addSublayer(layerWithLowerZPosition) after addSublayer(layerWithHigherZPosition). The resulting sublayers will be [layerWithHigherZPosition, layerWithLowerZPosition], representing a reversed order from the zPosition order(or visual order).

So it seems there are 2 kinds of layer ordering, which is very confusing. The docs should differentiate them clearly. At least the doc of  CALayer.sublayers shouldn't simply say "back to front order".

Or maybe the whole design of sublayers API is flawed: it's element order should never conflict zPosition order or visual order.

Steps to Reproduce:
1. Run sample app.
2. Read logs to see conflicting orders.

Code: https://cloudup.com/cxNm0lyGiDb