diff --git a/devtools/client/framework/toolbox.js b/devtools/client/framework/toolbox.js
index 303c9c36bc8d..f7acff1d04ce 100644
--- a/devtools/client/framework/toolbox.js
+++ b/devtools/client/framework/toolbox.js
@@ -2086,7 +2086,11 @@ Toolbox.prototype = {
     });
   },
 
-  // Returns an instance of the preference actor
+  /**
+   * Returns an instance of the preference actor. This is a lazily initialized root
+   * actor that persists preferences to the debuggee, instead of just to the DevTools
+   * client. See the definition of the preference actor for more information.
+   */
   get preferenceFront() {
     if (this._preferenceFront) {
       return Promise.resolve(this._preferenceFront);
diff --git a/devtools/server/actors/preference.js b/devtools/server/actors/preference.js
index 3fe7c5e129e1..eb44024c2f76 100644
--- a/devtools/server/actors/preference.js
+++ b/devtools/server/actors/preference.js
@@ -16,6 +16,16 @@ exports.register = function(handle) {
 exports.unregister = function(handle) {
 };
 
+/**
+ * Normally the preferences are set using Services.prefs, but this actor allows
+ * a debugger client to set preferences on the debuggee. This is particularly useful
+ * when remote debugging, and the preferences should persist to the remote target
+ * and not to the client. If used for a local target, it effectively behaves the same
+ * as using Services.prefs.
+ *
+ * This actor is used as a Root actor, targeting the entire browser, not an individual
+ * tab.
+ */
 var PreferenceActor = protocol.ActorClassWithSpec(preferenceSpec, {
 
   typeName: "preference",