Bug 1455017 - Document the preferences actor; r=jryans

MozReview-Commit-ID: 9wCanCMltHX

--HG--
extra : rebase_source : bce06d0d314ea083f4a350472513df88bb50d342

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);

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",