toolkit/modules/Deprecated.jsm

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 "use strict";
   6
   7 var EXPORTED_SYMBOLS = ["Deprecated"];
   8
   9 const PREF_DEPRECATION_WARNINGS = "devtools.errorconsole.deprecation_warnings";
  10
  11 const { Services } = ChromeUtils.import("resource://gre/modules/Services.jsm");
  12
  13 // A flag that indicates whether deprecation warnings should be logged.
  14 var logWarnings = Services.prefs.getBoolPref(PREF_DEPRECATION_WARNINGS);
  15
  16 Services.prefs.addObserver(PREF_DEPRECATION_WARNINGS, function(
  17   aSubject,
  18   aTopic,
  19   aData
  20 ) {
  21   logWarnings = Services.prefs.getBoolPref(PREF_DEPRECATION_WARNINGS);
  22 });
  23
  24 /**
  25  * Build a callstack log message.
  26  *
  27  * @param nsIStackFrame aStack
  28  *        A callstack to be converted into a string log message.
  29  */
  30 function stringifyCallstack(aStack) {
  31   // If aStack is invalid, use Components.stack (ignoring the last frame).
  32   if (!aStack || !(aStack instanceof Ci.nsIStackFrame)) {
  33     aStack = Components.stack.caller;
  34   }
  35
  36   let frame = aStack.caller;
  37   let msg = "";
  38   // Get every frame in the callstack.
  39   while (frame) {
  40     msg += frame.filename + " " + frame.lineNumber + " " + frame.name + "\n";
  41     frame = frame.caller;
  42   }
  43   return msg;
  44 }
  45
  46 var Deprecated = {
  47   /**
  48    * Log a deprecation warning.
  49    *
  50    * @param string aText
  51    *        Deprecation warning text.
  52    * @param string aUrl
  53    *        A URL pointing to documentation describing deprecation
  54    *        and the way to address it.
  55    * @param nsIStackFrame aStack
  56    *        An optional callstack. If it is not provided a
  57    *        snapshot of the current JavaScript callstack will be
  58    *        logged.
  59    */
  60   warning(aText, aUrl, aStack) {
  61     if (!logWarnings) {
  62       return;
  63     }
  64
  65     // If URL is not provided, report an error.
  66     if (!aUrl) {
  67       Cu.reportError(
  68         "Error in Deprecated.warning: warnings must " +
  69           "provide a URL documenting this deprecation."
  70       );
  71       return;
  72     }
  73
  74     let textMessage =
  75       "DEPRECATION WARNING: " +
  76       aText +
  77       "\nYou may find more details about this deprecation at: " +
  78       aUrl +
  79       "\n" +
  80       // Append a callstack part to the deprecation message.
  81       stringifyCallstack(aStack);
  82
  83     // Report deprecation warning.
  84     Cu.reportError(textMessage);
  85   },
  86 };