Bug 1044709 - Improve the comment describing the memory report file format. r=mccr8.
authorNicholas Nethercote <nnethercote@mozilla.com>
Sun, 28 Sep 2014 18:35:14 -0700
changeset 208904 d73853c26a1a571c1970295d71f38d075d9458ec
parent 208903 155f170fa5eaa95fd8026aa9982ba26b1fa45f21
child 208905 2b73787681bddb7b30b4b6c4c484278f10f582ab
push id1
push userroot
push dateMon, 20 Oct 2014 17:29:22 +0000
reviewersmccr8
bugs1044709
milestone35.0a1
Bug 1044709 - Improve the comment describing the memory report file format. r=mccr8.
xpcom/base/nsIMemoryInfoDumper.idl
--- a/xpcom/base/nsIMemoryInfoDumper.idl
+++ b/xpcom/base/nsIMemoryInfoDumper.idl
@@ -54,89 +54,39 @@ interface nsIMemoryInfoDumper : nsISuppo
    * @param aFilename The output file.
    *
    * @param aFinishDumping The callback called on completion.
    *
    * @param aFinishDumpingData The environment for the callback.
    *
    * @param aAnonymize Should the reports be anonymized?
    *
-   * Sample output:
+   * Sample output, annotated with comments for explanatory purposes.
    *
    * {
+   *   // The version number of the format, which will be incremented each time
+   *   // backwards-incompatible changes are made. A mandatory integer.
    *   "version": 1
+   *
+   *   // Equal to nsIMemoryReporterManager::hasMozMallocUsableSize. A
+   *   // mandatory boolean.
    *   "hasMozMallocUsableSize": true,
+   *
+   *   // The memory reports. A mandatory array.
    *   "reports": [
+   *     // The properties correspond to the arguments of
+   *     // nsIHandleReportCallback::callback. Every one is mandatory.
    *     {"process":"Main Process (pid 12345)", "path":"explicit/foo/bar",
    *      "kind":1, "units":0, "amount":2000000, "description":"Foo bar."},
    *     {"process":"Main Process (pid 12345)", "path":"heap-allocated",
    *      "kind":1, "units":0, "amount":3000000, "description":"Heap allocated."},
    *     {"process":"Main Process (pid 12345)", "path":"vsize",
    *      "kind":1, "units":0, "amount":10000000, "description":"Vsize."}
    *   ]
    * }
-   *
-   * JSON schema for the output.
-   *
-   * {
-   *   "properties": {
-   *     "version": {
-   *       "type": "integer",
-   *       "description": "Version number of this schema.",
-   *       "required": true
-   *     },
-   *     "hasMozMallocUsableSize": {
-   *       "type": "boolean",
-   *       "description": "nsIMemoryReporterManager::hasMozMallocUsableSize",
-   *       "required": true
-   *     },
-   *     "reports": {
-   *       "type": "array",
-   *       "description": "The memory reports.",
-   *       "required": true
-   *       "minItems": 1,
-   *       "items": {
-   *         "type": "object",
-   *         "properties": {
-   *           "process": {
-   *             "type": "string",
-   *             "description": "nsIMemoryReporter::process",
-   *             "required": true
-   *           },
-   *           "path": {
-   *             "type": "string",
-   *             "description": "nsIMemoryReporter::path",
-   *             "required": true,
-   *             "minLength": 1
-   *           },
-   *           "kind": {
-   *             "type": "integer",
-   *             "description": "nsIMemoryReporter::kind",
-   *             "required": true
-   *           },
-   *           "units": {
-   *             "type": "integer",
-   *             "description": "nsIMemoryReporter::units",
-   *             "required": true
-   *           },
-   *           "amount": {
-   *             "type": "integer",
-   *             "description": "nsIMemoryReporter::amount",
-   *             "required": true
-   *           },
-   *           "description": {
-   *             "type": "string",
-   *             "description": "nsIMemoryReporter::description",
-   *             "required": true
-   *           }
-   *         }
-   *       }
-   *     }
-   *   }
-   * }
    */
   void dumpMemoryReportsToNamedFile(in AString aFilename,
                                     in nsIFinishDumpingCallback aFinishDumping,
                                     in nsISupports aFinishDumpingData,
                                     in boolean aAnonymize);
 
   /**
    * Similar to dumpMemoryReportsToNamedFile, this method dumps gzipped memory