From bf5c87f0005f6314f1375696f2001e2cf646cf55 Mon Sep 17 00:00:00 2001 From: Markus Stange Date: Fri, 13 May 2016 23:50:24 -0400 Subject: [PATCH] Make better use of jsdocs --- .eslintrc.js | 3 +++ package.json | 4 +++- src/function-info.js | 6 +++--- src/preprocess-profile.js | 20 +++++++++++++++++- src/symbol-store-db.js | 6 +++++- src/symbol-store.js | 44 +++++++++++++++++++++++++-------------- 6 files changed, 61 insertions(+), 22 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 5151fee80f..c14ba10160 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -46,6 +46,9 @@ module.exports = { ], "eqeqeq": [ "error" + ], + "valid-jsdoc": [ + "error" ] }, "settings": { diff --git a/package.json b/package.json index a814ea352b..aaa6767d19 100644 --- a/package.json +++ b/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 ", "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", diff --git a/src/function-info.js b/src/function-info.js index 725bf53d54..1de1d5d74f 100644 --- a/src/function-info.js +++ b/src/function-info.js @@ -131,8 +131,8 @@ 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, @@ -140,7 +140,7 @@ function getRealScriptURI(url) { * 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) { diff --git a/src/preprocess-profile.js b/src/preprocess-profile.js index e89351c499..cd0a4365a0 100644 --- a/src/preprocess-profile.js +++ b/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); diff --git a/src/symbol-store-db.js b/src/symbol-store-db.js index a99f122ebc..b5dfaf1583 100644 --- a/src/symbol-store-db.js +++ b/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. */ diff --git a/src/symbol-store.js b/src/symbol-store.js index 5f5b2fb01c..0485de6a21 100644 --- a/src/symbol-store.js +++ b/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>} 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} 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>} 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)); } }