diff --git a/gfx/layers/CompositorTypes.h b/gfx/layers/CompositorTypes.h
index 227f541dd2ed..651ad124a08f 100644
--- a/gfx/layers/CompositorTypes.h
+++ b/gfx/layers/CompositorTypes.h
@@ -48,7 +48,6 @@ const TextureFlags TEXTURE_COMPONENT_ALPHA    = 1 << 5;
 // (for example, with GL), a BGRA shader should be used.
 const TextureFlags TEXTURE_RB_SWAPPED         = 1 << 6;
 
-// A texture host that supports tiling
 const TextureFlags TEXTURE_FRONT              = 1 << 12;
 // A texture host on white for component alpha
 const TextureFlags TEXTURE_ON_WHITE           = 1 << 13;
diff --git a/gfx/layers/client/CompositableClient.h b/gfx/layers/client/CompositableClient.h
index daf06ecd7d80..bd2c17d7ebf9 100644
--- a/gfx/layers/client/CompositableClient.h
+++ b/gfx/layers/client/CompositableClient.h
@@ -115,8 +115,11 @@ public:
 
   /**
    * This identifier is what lets us attach async compositables with a shadow
-   * layer. It is not used if the compositable is used with the regulat shadow
+   * layer. It is not used if the compositable is used with the regular shadow
    * layer forwarder.
+   *
+   * If this returns zero, it means the compositable is not async (it is used
+   * on the main thread).
    */
   uint64_t GetAsyncID() const;
 
@@ -141,8 +144,24 @@ public:
    */
   virtual void OnDetach() {}
 
+  /**
+   * When texture deallocation must happen on the client side, we need to first
+   * ensure that the compositor has already let go of the data in order
+   * to safely deallocate it.
+   *
+   * This is implemented by registering a callback to postpone deallocation or
+   * recycling of the shared data.
+   *
+   * This hook is called when the compositor notifies the client that it is not
+   * holding any more references to the shared data so that this compositable
+   * can run the corresponding callback.
+   */
   void OnReplyTextureRemoved(uint64_t aTextureID);
 
+  /**
+   * Run all he registered callbacks (see the comment for OnReplyTextureRemoved).
+   * Only call this if you know what you are doing.
+   */
   void FlushTexturesToRemoveCallbacks();
 protected:
   struct TextureIDAndFlags {
diff --git a/gfx/layers/client/TextureClient.h b/gfx/layers/client/TextureClient.h
index 1c6b798f23c3..2e0d0e5d2a20 100644
--- a/gfx/layers/client/TextureClient.h
+++ b/gfx/layers/client/TextureClient.h
@@ -124,12 +124,13 @@ public:
   virtual TextureClientSurface* AsTextureClientSurface() { return nullptr; }
   virtual TextureClientYCbCr* AsTextureClientYCbCr() { return nullptr; }
 
-  virtual void MarkUnused() {}
-
-  virtual bool Lock(OpenMode aMode)
-  {
-    return IsValid();
-  }
+  /**
+   * Locks the shared data, allowing the caller to get access to it.
+   *
+   * Please always lock/unlock when accessing the shared data.
+   * If Lock() returns false, you should not attempt to access the shared data.
+   */
+  virtual bool Lock(OpenMode aMode) { return IsValid(); }
 
   virtual void Unlock() {}
 
@@ -138,11 +139,18 @@ public:
    * Textures that do not implement locking should be immutable or should
    * use immediate uploads (see TextureFlags in CompositorTypes.h)
    */
-  virtual bool ImplementsLocking() const
-  {
-    return false;
-  }
+  virtual bool ImplementsLocking() const { return false; }
 
+  /**
+   * Sets this texture's ID.
+   *
+   * This ID is used to match a texture client with his corresponding TextureHost.
+   * Only the CompositableClient should be allowed to set or clear the ID.
+   * Zero is always an invalid ID.
+   * For a given compositableClient, there can never be more than one texture
+   * client with the same non-zero ID.
+   * Texture clients from different compositables may have the same ID.
+   */
   void SetID(uint64_t aID)
   {
     MOZ_ASSERT(mID == 0 && aID != 0);
@@ -155,10 +163,7 @@ public:
     mID = 0;
   }
 
-  uint64_t GetID() const
-  {
-    return mID;
-  }
+  uint64_t GetID() const { return mID; }
 
   virtual bool IsAllocated() const = 0;
 
@@ -166,8 +171,22 @@ public:
 
   virtual gfx::IntSize GetSize() const = 0;
 
+  /**
+   * Drop the shared data into a TextureClientData object and mark this
+   * TextureClient as invalid.
+   *
+   * The TextureClient must not hold any reference to the shared data
+   * after this method has been called.
+   * The TextureClientData is owned by the caller.
+   */
   virtual TextureClientData* DropTextureData() = 0;
 
+  /**
+   * TextureFlags contain important information about various aspects
+   * of the texture, like how its liferime is managed, and how it
+   * should be displayed.
+   * See TextureFlags in CompositorTypes.h.
+   */
   TextureFlags GetFlags() const { return mFlags; }
 
   /**
@@ -189,6 +208,10 @@ public:
    */
   bool IsValid() const { return mValid; }
 
+  /**
+   * An invalid TextureClient cannot provide access to its shared data
+   * anymore. This usually means it will soon be destroyed.
+   */
   void MarkInvalid() { mValid = false; }
 
 protected:
diff --git a/gfx/layers/composite/CompositableHost.h b/gfx/layers/composite/CompositableHost.h
index 5c5bc7de999a..af1eeae563b1 100644
--- a/gfx/layers/composite/CompositableHost.h
+++ b/gfx/layers/composite/CompositableHost.h
@@ -303,6 +303,14 @@ protected:
 
 class CompositableParentManager;
 
+/**
+ * IPDL actor used by CompositableHost to match with its corresponding
+ * CompositableClient on the content side.
+ *
+ * CompositableParent is owned by the IPDL system. It's deletion is triggered
+ * by either the CompositableChild's deletion, or by the IPDL communication
+ * goind down.
+ */
 class CompositableParent : public PCompositableParent
 {
 public: