Make Aura and compositor stacking methods more intuitive.

ui/gfx/compositor/layer.h

 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef UI_GFX_COMPOSITOR_LAYER_H_
 #define UI_GFX_COMPOSITOR_LAYER_H_
 #pragma once
 
 #include <string>
 #include <vector>
@@ skipping 54 matching lines @@
 
   // Adds a new Layer to this Layer.
   void Add(Layer* child);
 
   // Removes a Layer from this Layer.
   void Remove(Layer* child);
 
   // Stacks |child| above all other children.
   void StackAtTop(Layer* child);
 
-  // Stacks |child| above |other|, both of which must be children of this layer.
-  // Does nothing if |other| is already above |child|.
+  // Stacks |child| directly above |other|.  Both must be children of this
+  // layer.  Note that if |child| is initially stacked even higher, calling this
+  // method will result in |child| being lowered in the stacking order.
   void StackAbove(Layer* child, Layer* other);
 
   // Returns the child Layers.
   const std::vector<Layer*>& children() const { return children_; }
 
   // The parent.
   const Layer* parent() const { return parent_; }
   Layer* parent() { return parent_; }
 
   // Returns true if this Layer contains |other| somewhere in its children.
@@ skipping 207 matching lines @@
 #endif
 
   const LayerType type_;
 
   Compositor* compositor_;
 
   scoped_refptr<ui::Texture> texture_;
 
   Layer* parent_;
 
+  // This layer's children, in bottom-to-top stacking order.
   std::vector<Layer*> children_;
 
   ui::Transform transform_;
 
   gfx::Rect bounds_;
 
   // Visibility of this layer. See SetVisible/IsDrawn for more details.
   bool visible_;
 
   bool fills_bounds_opaquely_;
@@ skipping 19 matching lines @@
   WebKit::WebLayer web_layer_;
   bool web_layer_is_accelerated_;
 #endif
 
   DISALLOW_COPY_AND_ASSIGN(Layer);
 };
 
 }  // namespace ui
 
 #endif  // UI_GFX_COMPOSITOR_LAYER_H_