--- a/devtools/client/framework/toolbox.js
+++ b/devtools/client/framework/toolbox.js
@@ -2081,17 +2081,21 @@ Toolbox.prototype = {
                                 getUnicodeUrl(this.target.url));
     }
     this.postMessage({
       name: "set-host-title",
       title
     });
   },
 
-  // 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);
     }
     return this.isOpen.then(() => {
       return this.target.root.then(rootForm => {
         let front = getPreferenceFront(this.target.client, rootForm);
         this._preferenceFront = front;

--- a/devtools/server/actors/preference.js
+++ b/devtools/server/actors/preference.js
@@ -11,16 +11,26 @@ const {preferenceSpec} = require("devtoo
 
 exports.register = function(handle) {
   handle.addGlobalActor(PreferenceActor, "preferenceActor");
 };
 
 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",
 
   getBoolPref: function(name) {
     return Services.prefs.getBoolPref(name);
   },