ref: tsdoc stuff

lib/DataStore.ts

@@ -22,14 +22,14 @@ export type DataStoreOptions<TData> = Prettify<
      * The default data object to use if no data is saved in persistent storage yet.  
      * Until the data is loaded from persistent storage with {@linkcode DataStore.loadData()}, this will be the data returned by {@linkcode DataStore.getData()}.  
      *   
-     * ⚠️ This has to be an object that can be serialized to JSON using `JSON.stringify()`, so no functions or circular references are allowed, they will cause unexpected behavior.  
+     * - ⚠️ This has to be an object that can be serialized to JSON using `JSON.stringify()`, so no functions or circular references are allowed, they will cause unexpected behavior.  
      */
     defaultData: TData;
     /**
      * An incremental, whole integer version number of the current format of data.  
      * If the format of the data is changed in any way, this number should be incremented, in which case all necessary functions of the migrations dictionary will be run consecutively.  
      *   
-     * ⚠️ Never decrement this number and optimally don't skip any numbers either!
+     * - ⚠️ Never decrement this number and optimally don't skip any numbers either!
      */
     formatVersion: number;
     /**
@@ -87,12 +87,12 @@ export type DataStoreOptions<TData> = Prettify<
  * Supports migrating data from older format versions to newer ones and populating the cache with default data if no persistent data is found.  
  * Can be overridden to implement any other storage method.  
  *   
- * All methods are at least `protected`, so you can easily extend this class and overwrite them to use a different storage method or to add additional functionality.  
- * Remember that you can call `super.methodName()` in the subclass to access the original method.  
+ * All methods are `protected` or `public`, so you can easily extend this class and overwrite them to use a different storage method or to add other functionality.  
+ * Remember that you can use `super.methodName()` in the subclass to call the original method if needed.  
  *   
- * ⚠️ The stored data has to be **serializable using `JSON.stringify()`**, meaning no undefined, circular references, etc. are allowed.  
- * ⚠️ If the storageMethod is left as the default of `"GM"` the directives `@grant GM.getValue` and `@grant GM.setValue` are required. If you then also use the method {@linkcode DataStore.deleteData()}, the extra directive `@grant GM.deleteValue` is needed too.  
- * ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`  
+ * - ⚠️ The data is stored as a JSON string, so only data compatible with [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) can be used. Circular structures and complex objects (containing functions, symbols, etc.) will either throw an error on load and save or cause otherwise unexpected behavior. Properties with a value of `undefined` will be removed from the data prior to saving it, so use `null` instead.  
+ * - ⚠️ If the storageMethod is left as the default of `"GM"`, the directives `@grant GM.getValue` and `@grant GM.setValue` are required. If you then also use the method {@linkcode DataStore.deleteData()}, the extra directive `@grant GM.deleteValue` is needed too.  
+ * - ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`  
  * 
  * @template TData The type of the data that is saved in persistent storage for the currently set format version (will be automatically inferred from `defaultData` if not provided)
  */
@@ -111,8 +111,8 @@ export class DataStore<TData extends object = object> {
    * Creates an instance of DataStore to manage a sync & async database that is cached in memory and persistently saved across sessions.  
    * Supports migrating data from older versions to newer ones and populating the cache with default data if no persistent data is found.  
    *   
-   * ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue` if the storageMethod is left as the default of `"GM"`  
-   * ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`
+   * - ⚠️ Requires the directives `@grant GM.getValue` and `@grant GM.setValue` if the storageMethod is left as the default of `"GM"`  
+   * - ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`
    * 
    * @template TData The type of the data that is saved in persistent storage for the currently set format version (will be automatically inferred from `defaultData` if not provided) - **This has to be a JSON-compatible object!** (no undefined, circular references, etc.)
    * @param options The options for this DataStore instance
@@ -222,7 +222,7 @@ export class DataStore<TData extends object = object> {
    * The in-memory cache will be left untouched, so you may still access the data with {@linkcode getData()}  
    * Calling {@linkcode loadData()} or {@linkcode setData()} after this method was called will recreate persistent storage with the cached or default data.  
    *   
-   * ⚠️ This requires the additional directive `@grant GM.deleteValue` if the storageMethod is left as the default of `"GM"`
+   * - ⚠️ This requires the additional directive `@grant GM.deleteValue` if the storageMethod is left as the default of `"GM"`
    */
   public async deleteData(): Promise<void> {
     await Promise.all([
@@ -343,7 +343,7 @@ export class DataStore<TData extends object = object> {
 
   //#region storage
 
-  /** Gets a value from persistent storage - can be overwritten in a subclass if you want to use something other than GM storage */
+  /** Gets a value from persistent storage - can be overwritten in a subclass if you want to use something other than the default storage methods */
   protected async getValue<TValue extends GM.Value = string>(name: string, defaultValue: TValue): Promise<string | TValue> {
     switch(this.storageMethod) {
     case "localStorage":
@@ -356,7 +356,7 @@ export class DataStore<TData extends object = object> {
   }
 
   /**
-   * Sets a value in persistent storage - can be overwritten in a subclass if you want to use something other than GM storage.  
+   * Sets a value in persistent storage - can be overwritten in a subclass if you want to use something other than the default storage methods.  
    * The default storage engines will stringify all passed values like numbers or booleans, so be aware of that.
    */
   protected async setValue(name: string, value: GM.Value): Promise<void> {
@@ -370,7 +370,7 @@ export class DataStore<TData extends object = object> {
     }
   }
 
-  /** Deletes a value from persistent storage - can be overwritten in a subclass if you want to use something other than GM storage */
+  /** Deletes a value from persistent storage - can be overwritten in a subclass if you want to use something other than the default storage methods */
   protected async deleteValue(name: string): Promise<void> {
     switch(this.storageMethod) {
     case "localStorage":

lib/DataStoreSerializer.ts

@@ -35,7 +35,7 @@ export type LoadStoresDataResult = {
  * All methods are at least `protected`, so you can easily extend this class and overwrite them to use a different storage method or to add additional functionality.  
  * Remember that you can call `super.methodName()` in the subclass to access the original method.  
  *   
- * ⚠️ Needs to run in a secure context (HTTPS) due to the use of the SubtleCrypto API if checksumming is enabled.  
+ * - ⚠️ Needs to run in a secure context (HTTPS) due to the use of the SubtleCrypto API if checksumming is enabled.  
  */
 export class DataStoreSerializer {
   protected stores: DataStore[];

lib/crypto.ts

@@ -47,8 +47,8 @@ function str2ab(str: string): ArrayBuffer {
 /**
  * Creates a hash / checksum of the given {@linkcode input} string or ArrayBuffer using the specified {@linkcode algorithm} ("SHA-256" by default).  
  *   
- * ⚠️ Uses the SubtleCrypto API so it needs to run in a secure context (HTTPS).  
- * ⚠️ If you use this for cryptography, make sure to use a secure algorithm (under no circumstances use SHA-1) and to [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) your input data.
+ * - ⚠️ Uses the SubtleCrypto API so it needs to run in a secure context (HTTPS).  
+ * - ⚠️ If you use this for cryptography, make sure to use a secure algorithm (under no circumstances use SHA-1) and to [salt](https://en.wikipedia.org/wiki/Salt_(cryptography)) your input data.
  */
 export async function computeHash(input: string | ArrayBuffer, algorithm = "SHA-256"): Promise<string> {
   let data: ArrayBuffer;
@@ -69,7 +69,7 @@ export async function computeHash(input: string | ArrayBuffer, algorithm = "SHA-
 /**
  * Generates a random ID with the specified length and radix (16 characters and hexadecimal by default)  
  *   
- * ⚠️ Not suitable for generating anything related to cryptography! Use [SubtleCrypto's `generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that instead.
+ * - ⚠️ Not suitable for generating anything related to cryptography! Use [SubtleCrypto's `generateKey()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey) for that instead.
  * @param length The length of the ID to generate (defaults to 16)
  * @param radix The [radix](https://en.wikipedia.org/wiki/Radix) of each digit (defaults to 16 which is hexadecimal. Use 2 for binary, 10 for decimal, 36 for alphanumeric, etc.)
  * @param enhancedEntropy If set to true, uses [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) for better cryptographic randomness (this also makes it take longer to generate)  

lib/dom.ts

@@ -244,7 +244,7 @@ let ttPolicy: { createHTML: (html: string) => string } | undefined;
  * Uses a [Trusted Types policy](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types_API) on Chromium-based browsers to trick the browser into thinking the HTML is safe.  
  * Use this if the page makes use of the CSP directive `require-trusted-types-for 'script'` and throws a "This document requires 'TrustedHTML' assignment" error on Chromium-based browsers.  
  *   
- * ⚠️ This function does not perform any sanitization and should thus be used with utmost caution, as it can easily lead to XSS vulnerabilities!
+ * - ⚠️ This function does not perform any sanitization and should thus be used with utmost caution, as it can easily lead to XSS vulnerabilities!
  */
 export function setInnerHtmlUnsafe<TElement extends Element = HTMLElement>(element: TElement, html: string): TElement {
   // @ts-ignore

lib/translation.ts

@@ -84,7 +84,7 @@ function translate(language: string, key: string, ...args: Stringifiable[]): str
 * Use {@linkcode tr.forLang()} to get the translation for a specific language instead of the currently set one.  
 * If the key is not found in the currently set language, the key itself is returned.  
 *   
-* ⚠️ Remember to register a language with {@linkcode tr.addTranslations()} and set it as active with {@linkcode tr.setLanguage()} before using this function, otherwise it will always return the key itself.
+* - ⚠️ Remember to register a language with {@linkcode tr.addTranslations()} and set it as active with {@linkcode tr.setLanguage()} before using this function, otherwise it will always return the key itself.
 * @param key Key of the translation to return
 * @param args Optional arguments to be passed to the translated text. They will replace placeholders in the format `%n`, where `n` is the 1-indexed argument number
 */
@@ -94,7 +94,7 @@ const tr = (key: string, ...args: Stringifiable[]): string => translate(curLang,
 * Returns the translated text for the specified key in the specified language.  
 * If the key is not found in the specified previously registered translation, the key itself is returned.  
 *   
-* ⚠️ Remember to register a language with {@linkcode tr.addTranslations()} before using this function, otherwise it will always return the key itself.
+* - ⚠️ Remember to register a language with {@linkcode tr.addTranslations()} before using this function, otherwise it will always return the key itself.
 * @param language Language code or name to use for the translation
 * @param key Key of the translation to return
 * @param args Optional arguments to be passed to the translated text. They will replace placeholders in the format `%n`, where `n` is the 1-indexed argument number