From a6b3d6487288b1bd538ba8652ab88b7b3e8c2e45 Mon Sep 17 00:00:00 2001 From: Michael FIG Date: Thu, 11 Feb 2021 12:44:11 -0600 Subject: [PATCH] chore(swing-store-simple): update JSDoc to fix warnings --- .../swing-store-simple/simpleSwingStore.js | 50 ++++++++++--------- 1 file changed, 27 insertions(+), 23 deletions(-) diff --git a/packages/swing-store-simple/simpleSwingStore.js b/packages/swing-store-simple/simpleSwingStore.js index 4c6ec5250a5..b4d33c9c6d9 100644 --- a/packages/swing-store-simple/simpleSwingStore.js +++ b/packages/swing-store-simple/simpleSwingStore.js @@ -2,6 +2,10 @@ import fs from 'fs'; import path from 'path'; import Readlines from 'n-readlines'; +/** + * @typedef {ReturnType['storage']} SwingStore + */ + function safeUnlink(filePath) { try { fs.unlinkSync(filePath); @@ -19,7 +23,7 @@ function safeUnlink(filePath) { * that work on string keys and accept string values. A lot of kernel-side * code expects to get an object that implements the Storage API. * - * @returns an object: { + * returns an object: { * storage, // the storage API object itself * state // the underlying map that holds the state in memory * } @@ -30,9 +34,9 @@ function makeStorageInMemory() { /** * Test if the state contains a value for a given key. * - * @param key The key that is of interest. + * @param {string} key The key that is of interest. * - * @returns true if a value is stored for the key, false if not. + * @returns {boolean} true if a value is stored for the key, false if not. * * @throws if key is not a string. */ @@ -50,9 +54,9 @@ function makeStorageInMemory() { * Note that this can be slow as it's only intended for use in debugging and * test result verification. * - * @param start Start of the key range of interest (inclusive). An empty + * @param {string} start Start of the key range of interest (inclusive). An empty * string indicates a range from the beginning of the key set. - * @param end End of the key range of interest (exclusive). An empty string + * @param {string} end End of the key range of interest (exclusive). An empty string * indicates a range through the end of the key set. * * @yields an iterator for the keys from start <= key < end @@ -78,9 +82,9 @@ function makeStorageInMemory() { /** * Obtain the value stored for a given key. * - * @param key The key whose value is sought. + * @param {string} key The key whose value is sought. * - * @returns the (string) value for the given key, or undefined if there is no + * @returns {string|undefined} the (string) value for the given key, or undefined if there is no * such value. * * @throws if key is not a string. @@ -96,8 +100,8 @@ function makeStorageInMemory() { * Store a value for a given key. The value will replace any prior value if * there was one. * - * @param key The key whose value is being set. - * @param value The value to set the key to. + * @param {string} key The key whose value is being set. + * @param {string} value The value to set the key to. * * @throws if either parameter is not a string. */ @@ -115,7 +119,7 @@ function makeStorageInMemory() { * Remove any stored value for a given key. It is permissible for there to * be no existing stored value for the key. * - * @param key The key whose value is to be deleted + * @param {string} key The key whose value is to be deleted * * @throws if key is not a string. */ @@ -140,11 +144,11 @@ function makeStorageInMemory() { /** * Do the work of `initSwingStore` and `openSwingStore`. * - * @param dirPath Path to a directory in which database files may be kept, or + * @param {string} dirPath Path to a directory in which database files may be kept, or * null. - * @param forceReset If true, initialize the database to an empty state + * @param {boolean} [forceReset] If true, initialize the database to an empty state * - * @returns an object: { + * returns an object: { * storage, // a storage API object to load and store data * commit, // a function to commit changes made since the last commit * close // a function to shutdown the store, abandoning any uncommitted @@ -216,13 +220,13 @@ function makeSwingStore(dirPath, forceReset = false) { * serialized to a text file. If there is an existing store at the given * `dirPath`, it will be reinitialized to an empty state. * - * @param dirPath Path to a directory in which database files may be kept. + * @param {string} dirPath Path to a directory in which database files may be kept. * This directory need not actually exist yet (if it doesn't it will be * created) but it is reserved (by the caller) for the exclusive use of this * swing store instance. If this is nullish, the swing store created will * have no backing store and thus be non-persistent. * - * @returns an object: { + * returns an object: { * storage, // a storage API object to load and store data * commit, // a function to commit changes made since the last commit * close // a function to shutdown the store, abandoning any uncommitted @@ -241,12 +245,12 @@ export function initSwingStore(dirPath) { * a text file. If there is no existing store at the given `dirPath`, a new, * empty store will be created. * - * @param dirPath Path to a directory in which database files may be kept. + * @param {string} dirPath Path to a directory in which database files may be kept. * This directory need not actually exist yet (if it doesn't it will be * created) but it is reserved (by the caller) for the exclusive use of this * swing store instance. * - * @returns an object: { + * returns an object: { * storage, // a storage API object to load and store data * commit, // a function to commit changes made since the last commit * close // a function to shutdown the store, abandoning any uncommitted @@ -268,9 +272,9 @@ export function openSwingStore(dirPath) { * stupidest possible way, hence it is likely to be a performance and memory * hog if you attempt to use it on anything real. * - * @param storage The swing storage whose state is to be extracted. + * @param {SwingStore} storage The swing storage whose state is to be extracted. * - * @returns an array representing all the current state in `storage`, one + * @returns {Array<[string, string]>} an array representing all the current state in `storage`, one * element of the form [key, value] per key/value pair. */ export function getAllState(storage) { @@ -288,8 +292,8 @@ export function getAllState(storage) { * general store initialization mechanism. In particular, note that it does * not bother to remove any existing state in the store that it is given. * - * @param storage The swing storage whose state is to be set. - * @param stuff An array of key/value pairs, each element of the form [key, value] + * @param {SwingStore} storage The swing storage whose state is to be set. + * @param {Array<[string, string]>} stuff An array of key/value pairs, each element of the form [key, value] */ export function setAllState(storage, stuff) { for (const k of Object.getOwnPropertyNames(stuff)) { @@ -300,10 +304,10 @@ export function setAllState(storage, stuff) { /** * Is this directory a compatible swing store? * - * @param dirPath Path to a directory in which database files might be present. + * @param {string} dirPath Path to a directory in which database files might be present. * This directory need not actually exist * - * @returns boolean + * @returns {boolean} * If the directory is present and contains the files created by initSwingStore * or openSwingStore, returns true. Else returns false. *