Bug 507604 undeprecate the scriptable nsIDebug interface

r=bs sr=biesi

xpcom/base/nsIDebug.idl

@@ -38,25 +38,59 @@
 #include "nsISupports.idl"
 
 /**
- * @status DEPRECATED  Replaced by the NS_DebugBreak function.
  * @status FROZEN
+ *   For use by consumers in scripted languages (JavaScript, Java, Python,
+ *   Perl, ...).
+ *
+ * @note C/C++ consumers who are planning to use the nsIDebug interface with
+ *   the "@mozilla.org/xpcom;1" contract should use NS_DebugBreak from xpcom
+ *   glue instead.
+ *
  */
 
 [scriptable, uuid(3bf0c3d7-3bd9-4cf2-a971-33572c503e1e)]
 interface nsIDebug : nsISupports
 {
+  /**
+   * Show an assertion and trigger nsIDebug.break().
+   *
+   * @param aStr assertion message
+   * @param aExpr expression that failed
+   * @param aFile file containing assertion
+   * @param aLine line number of assertion
+   *
+   */
   void assertion(in string aStr,
                  in string aExpr,
                  in string aFile, 
                  in long aLine);
 
+  /**
+   * Show a warning.
+   *
+   * @param aStr warning message
+   * @param aFile file containing assertion
+   * @param aLine line number of assertion
+   */
   void warning(in string aStr,
                in string aFile,
                in long aLine);
-               
+
+  /**
+   * Request to break into a debugger.
+   *
+   * @param aFile file containing break request
+   * @param aLine line number of break request
+   */
   void break(in string aFile, 
              in long aLine);
 
+  /**
+   * Request the process to trigger a fatal abort.
+   *
+   * @param aFile file containing abort request
+   * @param aLine line number of abort request
+   */
   void abort(in string aFile, 
              in long aLine);
 };