Make better use of jsdocs

.eslintrc.js

@@ -46,6 +46,9 @@ module.exports = {
         ],
         "eqeqeq": [
             "error"
+        ],
+        "valid-jsdoc": [
+            "error"
         ]
     },
     "settings": {

package.json

@@ -12,7 +12,8 @@
     "build": "NODE_ENV=development webpack",
     "build-prod": "NODE_ENV=production webpack -p --progress",
     "eslint": "eslint index.js src",
-    "eslint-fix": "eslint --fix index.js src"
+    "eslint-fix": "eslint --fix index.js src",
+    "documentation": "documentation"
   },
   "author": "Markus Stange <[email protected]>",
   "license": "MIT",
@@ -28,6 +29,7 @@
     "bisection": "0.0.3",
     "browserify": "^12.0.1",
     "chai": "^3.5.0",
+    "documentation": "^4.0.0-beta2",
     "eslint": "^2.9.0",
     "eslint-config-google": "^0.5.0",
     "eslint-plugin-react": "^5.1.1",

src/function-info.js

@@ -131,16 +131,16 @@ function getRealScriptURI(url) {
 
 /**
  * Get an object with information about the function.
- * @param  string fullName The function name
- * @return object          An object of the form:
+ * @param  {string} fullName The function name
+ * @return {object}          An object of the form:
  *                           {
  *                             functionName: string,
  *                             libraryName: string,
  *                             lineInformation: string,
  *                             isRoot: bool,
  *                             isJSFrame: bool
  *                           }
- *                         libraryName is a string index into the resources array at the top of this file.
+ *                           libraryName is a string index into the resources array at the top of this file.
  */
 export function getFunctionInfo(fullName) {
 

src/preprocess-profile.js

@@ -4,10 +4,18 @@ import { resourceTypes } from './profile-data';
 import { provideHostSide } from './promise-worker';
 
 /**
- * Turn a data table from the form { schema, data } (as used in the raw profile
+ * Module for converting a profile into the 'preprocessed' format.
+ * @module preprocess-profile
+ */
+
+/**
+ * Turn a data table from the form `{ schema, data }` (as used in the raw profile
  * JSON) into a struct of arrays. This isn't very nice to read, but it
  * drastically reduces the number of JS objects the JS engine has to deal with,
  * resulting in fewer GC pauses and hopefully better performance.
+ *
+ * @param {object} rawTable A data table of the form `{ schema, data }`.
+ * @return {object} A data table of the form `{ length: number, field1: array, field2: array }`
  */
 function toStructOfArrays(rawTable) {
   const result = { length: rawTable.data.length };
@@ -30,6 +38,9 @@ function getRealScriptURI(url) {
 
 /**
  * Convert the given thread into preprocessed form.
+ * @param {object} thread The thread object, in the 'raw' format.
+ * @param {array} libs A libs array, in preprocessed format (as returned by preprocessSharedLibraries).
+ * @return {object} A new thread object in the 'preprocessed' format.
  */
 function preprocessThread(thread, libs) {
   const funcTable = {
@@ -132,6 +143,8 @@ function preprocessThread(thread, libs) {
 
 /**
  * Ensure every lib has pdbName and breakpadId fields, and sort them by start address.
+ * @param {string} libs The sharedLibrary JSON string as found in a profile in the 'raw' format.
+ * @return {array} An array of lib objects, sorted by startAddress.
  */
 function preprocessSharedLibraries(libs) {
   return JSON.parse(libs).map(lib => {
@@ -150,6 +163,9 @@ function preprocessSharedLibraries(libs) {
 
 /**
  * Adjust the "time" field by the given delta.
+ * @param {object} samplesOrMarkers The table of samples/markers.
+ * @param {number} delta The time delta, in milliseconds, by which to adjust.
+ * @return {object} A samples/markers table with adjusted time values.
  */
 function adjustTimestamps(samplesOrMarkers, delta) {
   return Object.assign({}, samplesOrMarkers, {
@@ -161,6 +177,8 @@ function adjustTimestamps(samplesOrMarkers, delta) {
  * Convert a profile from "raw" format into the preprocessed format.
  * For a description of the preprocessed format, look at the tests for this
  * function. (Sorry!)
+ * @param {object} profile A profile object, in the 'raw' format.
+ * @return {object} A new profile object, in the 'preprocessed' format.
  */
 export function preprocessProfile(profile) {
   const libs = preprocessSharedLibraries(profile.libs);

src/symbol-store-db.js

@@ -1,8 +1,12 @@
 import { provideHostSide } from './promise-worker';
 
+/**
+ * A wrapper around an IndexedDB table that stores symbol tables.
+ * @class SymbolStoreDB
+ * @classdesc Where does this description show up?
+ */
 export class SymbolStoreDB {
   /**
-   * SymbolStore constructor.
    * @param string dbName   The name of the indexedDB database that's used
    *                        to store the symbol tables.
    */

src/symbol-store.js

@@ -1,29 +1,30 @@
 import { SymbolStoreDB } from './symbol-store-db';
 
+/**
+ * Lets you get symbol tables and only requests them from the symbol provider once.
+ * @class SymbolStore
+ * @classdesc A broker that lets you request stuff as often as you want.
+ */
 export class SymbolStore {
   /**
    * SymbolStore constructor.
-   * @param string dbNamePrefix   A prefix for the indexedDB database which the SymbolStore
-   *                              uses internally (using asyncStorage) to store symbol tables.
-   * @param object symbolProvider An object with a method 'requestSymbolTable(pdbName, breakpadId)'
-   *                              which will be called whenever we need a symbol table. This method
-   *                              needs to return a promise of [addr, syms] (the symbol table).
+   * @param {string} dbNamePrefix   A prefix for the indexedDB database which the SymbolStore
+   *                                uses internally (using asyncStorage) to store symbol tables.
+   * @param {object} symbolProvider An object with a method 'requestSymbolTable(pdbName, breakpadId)'
+   *                                which will be called whenever we need a symbol table. This method
+   *                                needs to return a promise of [addr, syms] (the symbol table).
    */
   constructor(dbNamePrefix, symbolProvider) {
     this._symbolProvider = symbolProvider;
     this._db = new SymbolStoreDB(`${dbNamePrefix}-symbol-tables`);
 
-    /**
-     * A set of strings identifying libraries that we have requested
-     * symbols for but gotten an error back.
-     */
+    // A set of strings identifying libraries that we have requested
+    // symbols for but gotten an error back.
     this._failedRequests = new Set();
 
-    /**
-     * A map with one entry for each library that we have requested (but not yet
-     * received) symbols for. The keys are strings (libid), and the values are
-     * promises.
-     */
+    // A map with one entry for each library that we have requested (but not yet
+    // received) symbols for. The keys are strings (libid), and the values are
+    // promises.
     this._importingLibs = new Map();
   }
 
@@ -59,13 +60,24 @@ export class SymbolStore {
     });
   }
 
+  /**
+   * Get the array of symbol addresses for the given library.
+   * @param  {object} lib A library object with the properties `pdbName` and `breakpadId`.
+   * @return {Promise<Array<Number>>} A promise of the array of addresses.
+   */
   getFuncAddressTableForLib(lib) {
     return this._ensureLibraryIsInDB(lib).then(
       libKey => this._db.getFuncAddressTableForLib(libKey));
   }
 
-  getSymbolsForAddressesInLib(requestedAddresses, lib) {
+  /**
+   * Get an array of symbol strings for the given symbol indices.
+   * @param  {Array<Number>} requestedAddressesIndices An array where each element is the index of the symbol whose string should be looked up.
+   * @param  {Object} lib A library object with the properties `pdbName` and `breakpadId`.
+   * @return {Promise<Array<String>>} An promise array of strings, in the order as requested.
+   */
+  getSymbolsForAddressesInLib(requestedAddressesIndices, lib) {
     return this._ensureLibraryIsInDB(lib).then(
-      libKey => this._db.getSymbolsForAddressesInLib(requestedAddresses, libKey));
+      libKey => this._db.getSymbolsForAddressesInLib(requestedAddressesIndices, libKey));
   }
 }