--- a/gfx/layers/basic/BasicPaintedLayer.h
+++ b/gfx/layers/basic/BasicPaintedLayer.h
@@ -2,17 +2,17 @@
  * This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 #ifndef GFX_BASICPAINTEDLAYER_H
 #define GFX_BASICPAINTEDLAYER_H
 
 #include "Layers.h"                     // for PaintedLayer, LayerManager, etc
-#include "RotatedBuffer.h"              // for RotatedContentBuffer, etc
+#include "RotatedBuffer.h"              // for RotatedBuffer, etc
 #include "BasicImplData.h"              // for BasicImplData
 #include "BasicLayers.h"                // for BasicLayerManager
 #include "gfxPoint.h"                   // for gfxPoint
 #include "mozilla/RefPtr.h"             // for RefPtr
 #include "mozilla/gfx/BasePoint.h"      // for BasePoint
 #include "mozilla/layers/ContentClient.h"  // for ContentClientBasic
 #include "mozilla/mozalloc.h"           // for operator delete
 #include "nsDebug.h"                    // for NS_ASSERTION

--- a/gfx/layers/client/ClientPaintedLayer.h
+++ b/gfx/layers/client/ClientPaintedLayer.h
@@ -3,17 +3,17 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 #ifndef GFX_CLIENTPAINTEDLAYER_H
 #define GFX_CLIENTPAINTEDLAYER_H
 
 #include "ClientLayerManager.h"         // for ClientLayerManager, etc
 #include "Layers.h"                     // for PaintedLayer, etc
-#include "RotatedBuffer.h"              // for RotatedContentBuffer, etc
+#include "RotatedBuffer.h"              // for RotatedBuffer, etc
 #include "mozilla/Attributes.h"         // for override
 #include "mozilla/RefPtr.h"             // for RefPtr
 #include "mozilla/layers/ContentClient.h"  // for ContentClient
 #include "mozilla/mozalloc.h"           // for operator delete
 #include "nsDebug.h"                    // for NS_ASSERTION
 #include "nsISupportsImpl.h"            // for MOZ_COUNT_CTOR, etc
 #include "nsRegion.h"                   // for nsIntRegion
 #include "mozilla/layers/PLayerTransaction.h" // for PaintedLayerAttributes

--- a/gfx/layers/client/ContentClient.cpp
+++ b/gfx/layers/client/ContentClient.cpp
@@ -143,18 +143,17 @@ ContentClient::BeginPaintBuffer(PaintedL
                            dest.mValidRegion);
 
   if (result.mRegionToDraw.IsEmpty())
     return result;
 
   if (mBuffer) {
     if (mBuffer->Lock(LockMode())) {
       // Do not modify result.mRegionToDraw or result.mContentType after this call.
-      // Do not modify mBufferRect, mBufferRotation, or mDidSelfCopy,
-      // or call CreateBuffer before this call.
+      // Do not modify the back buffer's bufferRect, bufferRotation, or didSelfCopy.
       FinalizeFrame(result.mRegionToDraw);
     } else {
       // Abandon everything and redraw it all. Ideally we'd reallocate and copy
       // the old to the new and then call FinalizeFrame on the new buffer so that
       // we only need to draw the latest bits, but we need a big refactor to support
       // that ordering.
       result.mRegionToDraw = dest.mNeededRegion;
       dest.mCanReuseBuffer = false;

--- a/gfx/layers/client/ContentClient.h
+++ b/gfx/layers/client/ContentClient.h
@@ -2,17 +2,17 @@
  * This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 #ifndef MOZILLA_GFX_CONTENTCLIENT_H
 #define MOZILLA_GFX_CONTENTCLIENT_H
 
 #include <stdint.h>                     // for uint32_t
-#include "RotatedBuffer.h"              // for RotatedContentBuffer, etc
+#include "RotatedBuffer.h"              // for RotatedBuffer, etc
 #include "gfxTypes.h"
 #include "gfxPlatform.h"                // for gfxPlatform
 #include "mozilla/Assertions.h"         // for MOZ_CRASH
 #include "mozilla/Attributes.h"         // for override
 #include "mozilla/RefPtr.h"             // for RefPtr, already_AddRefed
 #include "mozilla/gfx/Point.h"          // for IntSize
 #include "mozilla/layers/CompositableClient.h"  // for CompositableClient
 #include "mozilla/layers/CompositableForwarder.h"
@@ -38,45 +38,27 @@ class DrawTarget;
 namespace layers {
 
 class PaintedLayer;
 class CapturedPaintState;
 
 /**
  * A compositable client for PaintedLayers. These are different to Image/Canvas
  * clients due to sending a valid region across IPC and because we do a lot more
- * optimisation work, encapsualted in RotatedContentBuffers.
+ * optimisation work, encapsulated in RotatedBuffers.
  *
  * We use content clients for OMTC and non-OMTC, basic rendering so that
  * BasicPaintedLayer has only one interface to deal with. We support single and
  * double buffered flavours. For tiled layers, we do not use a ContentClient
  * although we do have a ContentHost, and we do use texture clients and texture
  * hosts.
  *
  * The interface presented by ContentClient is used by the BasicPaintedLayer
  * methods - PaintThebes, which is the same for MT and OMTC, and PaintBuffer
- * which is different (the OMTC one does a little more). The 'buffer' in the
- * names of a lot of these method is actually the TextureClient. But, 'buffer'
- * for the RotatedContentBuffer (as in SetBuffer) means a gfxSurface. See the
- * comments for SetBuffer and SetBufferProvider in RotatedContentBuffer. To keep
- * these mapped buffers alive, we store a pointer in mOldTextures if the
- * RotatedContentBuffer's surface is not the one from our texture client, once we
- * are done painting we unmap the surface/texture client and don't need to keep
- * it alive anymore, so we clear mOldTextures.
- *
- * The sequence for painting is: call BeginPaint on the content client;
- * call BeginPaintBuffer on the content client. That will initialise the buffer
- * for painting, by calling RotatedContentBuffer::BeginPaint (usually) which
- * will call back to ContentClient::FinalizeFrame to finalize update of the
- * buffers before drawing (i.e., it finalizes the previous frame). Then call
- * BorrowDrawTargetForPainting to get a DrawTarget to paint into. Then paint.
- * Then return that DrawTarget using ReturnDrawTarget.
- * Call EndPaint on the content client;
- *
- * SwapBuffers is called in response to the transaction reply from the compositor.
+ * which is different (the OMTC one does a little more).
  */
 class ContentClient : public CompositableClient
 {
 public:
   typedef gfxContentType ContentType;
 
   /**
    * Creates, configures, and returns a new content client. If necessary, a
@@ -108,17 +90,17 @@ public:
 
   virtual void PrintInfo(std::stringstream& aStream, const char* aPrefix);
 
   virtual void Clear();
 
   /**
    * This is returned by BeginPaint. The caller should draw into mTarget.
    * mRegionToDraw must be drawn. mRegionToInvalidate has been invalidated
-   * by RotatedContentBuffer and must be redrawn on the screen.
+   * by ContentClient and must be redrawn on the screen.
    * mRegionToInvalidate is set when the buffer has changed from
    * opaque to transparent or vice versa, since the details of rendering can
    * depend on the buffer type.
    */
   struct PaintState {
     PaintState()
       : mRegionToDraw()
       , mRegionToInvalidate()
@@ -220,37 +202,53 @@ protected:
     nsIntRegion mValidRegion;
     gfx::IntRect mBufferRect;
     SurfaceMode mBufferMode;
     gfxContentType mBufferContentType;
     bool mCanReuseBuffer;
     bool mCanKeepBufferContents;
   };
 
+  /**
+   * Decide whether we can keep our current buffer and its contents,
+   * and return a struct containing the regions to paint, invalidate,
+   * the new buffer rect, surface mode, and content type.
+   */
   BufferDecision CalculateBufferForPaint(PaintedLayer* aLayer,
                                          uint32_t aFlags);
 
   /**
-   * Return the buffer's content type.  Requires a valid buffer or
-   * buffer provider.
+   * Return the buffer's content type.  Requires a valid buffer.
    */
   gfxContentType BufferContentType();
+  /**
+   * Returns whether the specified size is adequate for the current
+   * buffer and buffer size policy.
+   */
   bool BufferSizeOkFor(const gfx::IntSize& aSize);
 
+  /**
+   * Returns what open mode to use on texture clients. Ignored when
+   * using basic content clients.
+   */
   OpenMode LockMode() const;
 
   /**
    * Any actions that should be performed at the last moment before we begin
    * rendering the next frame. I.e., after we calculate what we will draw,
    * but before we rotate the buffer and possibly create new buffers.
    * aRegionToDraw is the region which is guaranteed to be overwritten when
    * drawing the next frame.
    */
   virtual void FinalizeFrame(const nsIntRegion& aRegionToDraw) {}
 
+  /**
+   * Create a new rotated buffer for the specified content type, buffer rect,
+   * and buffer flags.
+   */
   virtual RefPtr<RotatedBuffer> CreateBuffer(gfxContentType aType,
                                              const gfx::IntRect& aRect,
                                              uint32_t aFlags) = 0;
 
   RefPtr<RotatedBuffer> mBuffer;
   BufferSizePolicy      mBufferSizePolicy;
   bool mInAsyncPaint;
 };
@@ -282,31 +280,30 @@ protected:
                                              const gfx::IntRect& aRect,
                                              uint32_t aFlags) override;
 
 private:
   gfx::BackendType mBackend;
 };
 
 /**
- * A ContentClient backed by a RotatedContentBuffer.
+ * A ContentClient backed by a RemoteRotatedBuffer.
  *
  * When using a ContentClientRemoteBuffer, SurfaceDescriptors are created on
  * the rendering side and destroyed on the compositing side. They are only
  * passed from one side to the other when the TextureClient/Hosts are created.
  * *Ownership* of the SurfaceDescriptor moves from the rendering side to the
  * compositing side with the create message (send from CreateBuffer) which
  * tells the compositor that TextureClients have been created and that the
  * compositor should assign the corresponding TextureHosts to our corresponding
  * ContentHost.
  *
  * If the size or type of our buffer(s) change(s), then we simply destroy and
  * create them.
  */
-// Version using new texture clients
 class ContentClientRemoteBuffer : public ContentClient
 {
 public:
   explicit ContentClientRemoteBuffer(CompositableForwarder* aForwarder)
     : ContentClient(aForwarder, ContainsVisibleBounds)
     , mIsNewBuffer(false)
   {}
 
@@ -314,42 +311,36 @@ public:
                     const char* aPrefix="",
                     bool aDumpHtml=false,
                     TextureDumpMode aCompress=TextureDumpMode::Compress) override;
 
   virtual RefPtr<CapturedPaintState> BorrowDrawTargetForRecording(PaintState& aPaintState,
                                                                   RotatedBuffer::DrawIterator* aIter,
                                                                   bool aSetTransform) override;
 
-  /**
-   * Begin/End Paint map a gfxASurface from the texture client
-   * into the buffer of RotatedBuffer. The surface is only
-   * valid when the texture client is locked, so is mapped out
-   * of RotatedContentBuffer when we are done painting.
-   * None of the underlying buffer attributes (rect, rotation)
-   * are affected by mapping/unmapping.
-   */
   virtual void BeginPaint() override;
   virtual void BeginAsyncPaint() override;
   virtual void EndPaint(nsTArray<ReadbackProcessor::Update>* aReadbackUpdates = nullptr) override;
 
   virtual void Updated(const nsIntRegion& aRegionToDraw,
                        const nsIntRegion& aVisibleRegion);
 
   virtual TextureFlags ExtraTextureFlags() const
   {
     return TextureFlags::IMMEDIATE_UPLOAD;
   }
 
 protected:
   virtual nsIntRegion GetUpdatedRegion(const nsIntRegion& aRegionToDraw,
                                        const nsIntRegion& aVisibleRegion);
 
-  // Ensure we have a valid back buffer if we have a valid front buffer (i.e.
-  // if a backbuffer has been created.)
+  /**
+   * Ensure we have a valid back buffer if we have a valid front buffer (i.e.
+   * if a backbuffer has been created.)
+   */
   virtual void EnsureBackBufferIfFrontBuffer() {}
 
   virtual RefPtr<RotatedBuffer> CreateBuffer(gfxContentType aType,
                                              const gfx::IntRect& aRect,
                                              uint32_t aFlags) override;
 
   RefPtr<RotatedBuffer> CreateBufferInternal(const gfx::IntRect& aRect,
                                              gfx::SurfaceFormat aFormat,
@@ -359,25 +350,23 @@ protected:
   {
     return static_cast<RemoteRotatedBuffer*>(mBuffer.get());
   }
 
   bool mIsNewBuffer;
 };
 
 /**
- * A double buffered ContentClient. mTextureClient is the back buffer, which
- * we draw into. mFrontClient is the front buffer which we may read from, but
- * not write to, when the compositor does not have the 'soft' lock. We can write
- * into mTextureClient at any time.
+ * A double buffered ContentClientRemoteBuffer. mBuffer is the back buffer, which
+ * we draw into. mFrontBuffer is the front buffer which we may read from, but
+ * not write to, when the compositor does not have the 'soft' lock.
  *
  * The ContentHost keeps a reference to both corresponding texture hosts, in
  * response to our UpdateTextureRegion message, the compositor swaps its
- * references. In response to the compositor's reply we swap our references
- * (in SwapBuffers).
+ * references.
  */
 class ContentClientDoubleBuffered : public ContentClientRemoteBuffer
 {
 public:
   explicit ContentClientDoubleBuffered(CompositableForwarder* aFwd)
     : ContentClientRemoteBuffer(aFwd)
     , mFrontAndBackBufferDiffer(false)
   {}
@@ -411,22 +400,22 @@ public:
 
 private:
   RefPtr<RemoteRotatedBuffer> mFrontBuffer;
   nsIntRegion mFrontUpdatedRegion;
   bool mFrontAndBackBufferDiffer;
 };
 
 /**
- * A single buffered ContentClient. We have a single TextureClient/Host
- * which we update and then send a message to the compositor that we are
- * done updating. It is not safe for the compositor to use the corresponding
- * TextureHost's memory directly, it must upload it to video memory of some
- * kind. We are free to modify the TextureClient once we receive reply from
- * the compositor.
+ * A single buffered ContentClientRemoteBuffer. We have a single
+ * TextureClient/Host which we update and then send a message to the
+ * compositor that we are done updating. It is not safe for the compositor
+ * to use the corresponding TextureHost's memory directly, it must upload
+ * it to video memory of some kind. We are free to modify the TextureClient
+ * once we receive reply from the compositor.
  */
 class ContentClientSingleBuffered : public ContentClientRemoteBuffer
 {
 public:
   explicit ContentClientSingleBuffered(CompositableForwarder* aFwd)
     : ContentClientRemoteBuffer(aFwd)
   {
   }

--- a/gfx/layers/composite/ContentHost.h
+++ b/gfx/layers/composite/ContentHost.h
@@ -5,17 +5,17 @@
 
 #ifndef GFX_CONTENTHOST_H
 #define GFX_CONTENTHOST_H
 
 #include <stdint.h>                     // for uint32_t
 #include <stdio.h>                      // for FILE
 #include "mozilla-config.h"             // for MOZ_DUMP_PAINTING
 #include "CompositableHost.h"           // for CompositableHost, etc
-#include "RotatedBuffer.h"              // for RotatedContentBuffer, etc
+#include "RotatedBuffer.h"              // for RotatedBuffer, etc
 #include "mozilla/Attributes.h"         // for override
 #include "mozilla/RefPtr.h"             // for RefPtr
 #include "mozilla/gfx/BasePoint.h"      // for BasePoint
 #include "mozilla/gfx/MatrixFwd.h"      // for Matrix4x4
 #include "mozilla/gfx/Point.h"          // for Point
 #include "mozilla/gfx/Polygon.h"        // for Polygon
 #include "mozilla/gfx/Rect.h"           // for Rect
 #include "mozilla/gfx/Types.h"          // for SamplingFilter