Bug 794280 - Improve comment for SpecialPowers.pushPrefEnv(). r=ted DONTBUILD
authorJustin Lebar <justin.lebar@gmail.com>
Tue, 02 Oct 2012 12:04:24 -0400
changeset 109018 02f0c3cf55754a5ed530e42fbfbe98c1ef5b3bb4
parent 109017 9fec17552df2b1b12b506e464768e2d3026e1cec
child 109019 6b900e03eb58a0c9b26d889dfd6692f436ee2e59
push id82
push usershu@rfrn.org
push dateFri, 05 Oct 2012 13:20:22 +0000
reviewersted
bugs794280
milestone18.0a1
Bug 794280 - Improve comment for SpecialPowers.pushPrefEnv(). r=ted DONTBUILD
testing/specialpowers/content/specialpowersAPI.js
--- a/testing/specialpowers/content/specialpowersAPI.js
+++ b/testing/specialpowers/content/specialpowersAPI.js
@@ -471,27 +471,40 @@ SpecialPowersAPI.prototype = {
     var crashDumpFiles = this._sendSyncMessage("SPProcessCrashService", message)[0];
     crashDumpFiles.forEach(function(aFilename) {
       self._unexpectedCrashDumpFiles[aFilename] = true;
     });
     return crashDumpFiles;
   },
 
   /*
-   * Take in a list of prefs and put the original value on the _prefEnvUndoStack so we can undo
-   * preferences that we set.  Note, that this is a stack of values to revert to, not
-   * what we have set.
+   * Take in a list of pref changes to make, and invoke |callback| once those
+   * changes have taken effect.  When the test finishes, these changes are
+   * reverted.
+   *
+   * |inPrefs| must be an object with up to two properties: "set" and "clear".
+   * pushPrefEnv will set prefs as indicated in |inPrefs.set| and will unset
+   * the prefs indicated in |inPrefs.clear|.
+   *
+   * For example, you might pass |inPrefs| as:
    *
-   * prefs: {set|clear: [[pref, value], [pref, value, Iid], ...], set|clear: [[pref, value], ...], ...}
-   * ex: {'set': [['foo.bar', 2], ['browser.magic', '0xfeedface']], 'clear': [['bad.pref']] }
+   *  inPrefs = {'set': [['foo.bar', 2], ['magic.pref', 'baz']],
+   *             'clear': [['clear.this'], ['also.this']] };
+   *
+   * Notice that |set| and |clear| are both an array of arrays.  In |set|, each
+   * of the inner arrays must have the form [pref_name, value] or [pref_name,
+   * value, iid].  (The latter form is used for prefs with "complex" values.)
    *
-   * In the scenario where our prefs specify the same pref more than once, we do not guarantee
-   * the behavior.  
+   * In |clear|, each inner array should have the form [pref_name].
    *
-   * If a preference is not changing a value, we will ignore it.
+   * If you set the same pref more than once (or both set and clear a pref),
+   * the behavior of this method is undefined.
+   *
+   * (Implementation note: _prefEnvUndoStack is a stack of values to revert to,
+   * not values which have been set!)
    *
    * TODO: complex values for original cleanup?
    *
    */
   pushPrefEnv: function(inPrefs, callback) {
     var prefs = Components.classes["@mozilla.org/preferences-service;1"].
                            getService(Components.interfaces.nsIPrefBranch);