--- a/dom/ipc/PContent.ipdl
+++ b/dom/ipc/PContent.ipdl
@@ -338,16 +338,21 @@ struct GMPAPITags
 
 struct GMPCapabilityData
 {
     nsCString name;
     nsCString version;
     GMPAPITags[] capabilities;
 };
 
+/**
+ * The PContent protocol is a top-level protocol between the UI process
+ * and a content process. There is exactly one PContentParent/PContentChild pair
+ * for each content process.
+ */
 nested(upto inside_cpow) sync protocol PContent
 {
     parent spawns PPluginModule;
 
     parent opens PGMPService;
     child opens PBackground;
 
     manages PBlob;

--- a/gfx/layers/ipc/PCompositorBridge.ipdl
+++ b/gfx/layers/ipc/PCompositorBridge.ipdl
@@ -35,19 +35,39 @@ using class mozilla::layers::FrameUnifor
 using mozilla::layers::TextureFlags from "mozilla/layers/CompositorTypes.h";
 using mozilla::layers::CompositorOptions from "mozilla/layers/CompositorOptions.h";
 
 namespace mozilla {
 namespace layers {
 
 
 /**
- * The PCompositorBridge protocol is used to manage communication between
- * the main thread and the compositor thread context. It's primary
- * purpose is to manage the PLayerTransaction sub protocol.
+ * The PCompositorBridge protocol is a top-level protocol for the compositor.
+ * There is an instance of the protocol for each compositor, plus one for each
+ * content process. In other words:
+ * - There is a CompositorBridgeParent/CompositorBridgeChild pair created
+ *   for each "top level browser window", which has its own compositor. The
+ *   CompositorBridgeChild instance lives in the UI process, and the
+ *   CompositorBridgeParent lives in the GPU process (if there is one) or the
+ *   UI process otherwise.
+ * - There is also a CrossProcessCompositorBridgeParent/CompositorBridgeChild
+ *   pair created for each content process. The CrossProcessCompositorBridgeParent
+ *   lives in the GPU process (if there is one) or the UI process otherwise. The
+ *   CompositorBridgeChild is a singleton in the content process. Note that
+ *   a given content process may have multiple browser instances (represented
+ *   by TabChild instances), that are attached to different windows, and therefore
+ *   rendered by different compositors. This means that when a browser instance
+ *   sends messages via its CompositorBridgeChild, the corresponding
+ *   CrossProcessCompositorBridgeParent has to use the layers id in the message
+ *   to find the correct compositor or CompositorBridgeParent to pass the message
+ *   on to.
+ *
+ * One of the main goals of this protocol is to manage the PLayerTransaction sub-
+ * protocol, which is per-browser. A lot of the functions in the protocol are
+ * basically multiplexing/demultiplexing stuff in PLayerTransaction.
  */
 sync protocol PCompositorBridge
 {
   manages PAPZ;
   manages PAPZCTreeManager;
   // A Compositor manages a single Layer Manager (PLayerTransaction)
   manages PLayerTransaction;
   manages PTexture;

--- a/gfx/layers/ipc/PLayerTransaction.ipdl
+++ b/gfx/layers/ipc/PLayerTransaction.ipdl
@@ -33,16 +33,24 @@ using mozilla::layers::LayerHandle from 
 namespace mozilla {
 namespace layers {
 
 union MaybeTransform {
   Matrix4x4;
   void_t;
 };
 
+/**
+ * The PLayerTransaction protocol manages the layer tree for a single "browser".
+ * The "browser" can be a top-level browser window, in which case the PLayer-
+ * TransactionChild exists in the UI process. The "browser" can also be a content
+ * tab, in which case the PLayerTransactionChild exists in the content process.
+ * In either case, the PLayerTransactionParent exists in the GPU process (if
+ * there is one) or the UI process otherwise.
+ */
 sync protocol PLayerTransaction {
   manager PCompositorBridge;
   manages PCompositable;
 
 parent:
   async PCompositable(TextureInfo aTextureInfo);
 
   // The isFirstPaint flag can be used to indicate that this is the first update