- * When added to the stage, a layer can be ordered relative to other layers. The bottom
- * layer is at depth zero. The stage provides a default layer for it's children.
+ * When added to the stage, a layer can be ordered relative to other
+ * layers. The bottom layer is at depth zero. The stage provides a default
+ * layer for it's children (see Stage::GetRootLayer()).
+ *
+ * Layered actors inherit position etc. as normal, but are drawn in an order
+ * determined by the layers. In case of LAYER_3D, the depth buffer is cleared
+ * before each layer is rendered unless depth test is disabled or there's no
+ * need for it based on the layer's contents; actors in lower layers cannot
+ * obscure actors in higher layers.
+ *
+ * A layer has either LAYER_UI or LAYER_3D mode. LAYER_UI has better
+ * performance, the depth test is disabled, and a child actor hides its
+ * parent actor. LAYER_3D uses the depth test, thus a close actor hides a
+ * farther one. LAYER_UI is the default mode and recommended for general
+ * cases. See Layer::Behavior and SetBehavior() for more information.