From 009ff2e42462e2944dddf35c3260078769688414 Mon Sep 17 00:00:00 2001
From: Bauke <me@bauke.xyz>
Date: Thu, 29 Jun 2023 18:44:30 +0200
Subject: [PATCH] Add documentation.

---
 source/storage/enums.ts             |  6 ++++++
 source/storage/exports.ts           | 13 +++++++++++++
 source/storage/migrations/v1-1-2.ts |  9 +++++++++
 source/storage/user-label.ts        |  6 ++++++
 source/storage/username-color.ts    |  6 ++++++
 5 files changed, 40 insertions(+)

diff --git a/source/storage/enums.ts b/source/storage/enums.ts
index c40eece..8492cc2 100644
--- a/source/storage/enums.ts
+++ b/source/storage/enums.ts
@@ -1,3 +1,6 @@
+/**
+ * Keys of feature names used in WebExtension storage.
+ */
 export enum Feature {
   AnonymizeUsernames = "anonymize-usernames",
   Autocomplete = "autocomplete",
@@ -11,6 +14,9 @@ export enum Feature {
   UsernameColors = "username-colors",
 }
 
+/**
+ * Keys of miscellaneous data stored in WebExtension storage.
+ */
 export enum Data {
   EnabledFeatures = "enabled-features",
   KnownGroups = "known-groups",
diff --git a/source/storage/exports.ts b/source/storage/exports.ts
index 24907e6..96ffd80 100644
--- a/source/storage/exports.ts
+++ b/source/storage/exports.ts
@@ -8,6 +8,9 @@ export * from "./enums.js";
 export * from "./username-color.js";
 export * from "./user-label.js";
 
+/**
+ * The data stored for the Hide Votes feature.
+ */
 export type HideVotesData = {
   otherComments: boolean;
   otherTopics: boolean;
@@ -15,6 +18,9 @@ export type HideVotesData = {
   ownTopics: boolean;
 };
 
+/**
+ * All storage {@link Value}s stored in WebExtension storage.
+ */
 export const storageValues = {
   [Data.EnabledFeatures]: createValue({
     deserialize: (input) => new Set(JSON.parse(input) as Feature[]),
@@ -65,8 +71,15 @@ export const storageValues = {
   [Feature.UsernameColors]: collectUsernameColors(),
 };
 
+/**
+ * Shorthand for the inferred shape of {@link storageValues}.
+ */
 type StorageValues = typeof storageValues;
 
+/**
+ * Return the {@link Value}-wrapped data associated with a particular key.
+ * @param key The key of the value to get from {@link storageValues}.
+ */
 export async function fromStorage<K extends keyof StorageValues>(
   key: K,
 ): Promise<StorageValues[K]> {
diff --git a/source/storage/migrations/v1-1-2.ts b/source/storage/migrations/v1-1-2.ts
index 5ad04cb..e3ffa69 100644
--- a/source/storage/migrations/v1-1-2.ts
+++ b/source/storage/migrations/v1-1-2.ts
@@ -1,3 +1,6 @@
+/**
+ * The deserialize data function from version 1.1.2 and before.
+ */
 export function v112DeserializeData(data: Record<string, any>): {
   userLabels: V112Settings["data"]["userLabels"];
   usernameColors: V112Settings["data"]["usernameColors"];
@@ -22,6 +25,9 @@ export function v112DeserializeData(data: Record<string, any>): {
   return deserialized;
 }
 
+/**
+ * The Settings data structure from version 1.1.2 and before.
+ */
 export type V112Settings = {
   [index: string]: any;
   data: {
@@ -61,6 +67,9 @@ export type V112Settings = {
   version: string;
 };
 
+/**
+ * A sample of the version 1.1.2 Settings data to use in testing.
+ */
 export const v112Sample: V112Settings = {
   data: {
     hideVotes: {
diff --git a/source/storage/user-label.ts b/source/storage/user-label.ts
index 008db4d..2d7a759 100644
--- a/source/storage/user-label.ts
+++ b/source/storage/user-label.ts
@@ -2,6 +2,9 @@ import {createValue, type Value} from "@holllo/webextension-storage";
 import browser from "webextension-polyfill";
 import {Feature} from "./enums.js";
 
+/**
+ * The data structure for a user label.
+ */
 export type UserLabel = {
   color: string;
   id: number;
@@ -10,6 +13,9 @@ export type UserLabel = {
   username: string;
 };
 
+/**
+ * Shorthand for an array of {@link Value}-wrapped {@link UserLabel}s.
+ */
 export type UserLabelsData = Array<Value<UserLabel>>;
 
 /**
diff --git a/source/storage/username-color.ts b/source/storage/username-color.ts
index 77b4742..7b9874c 100644
--- a/source/storage/username-color.ts
+++ b/source/storage/username-color.ts
@@ -2,12 +2,18 @@ import {type Value, createValue} from "@holllo/webextension-storage";
 import browser from "webextension-polyfill";
 import {Feature} from "./enums.js";
 
+/**
+ * The data structure for a username color.
+ */
 export type UsernameColor = {
   color: string;
   id: number;
   username: string;
 };
 
+/**
+ * Shorthand for an array of {@link Value}-wrapped {@link UsernameColor}s.
+ */
 export type UsernameColorsData = Array<Value<UsernameColor>>;
 
 /**