Merge pull request #2399 from Agoric/mfig-jsdoc-simple-store

chore(swing-store-simple): update JSDoc to fix warnings

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<typeof makeStorageInMemory>['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.
  *