From 2e0ea982252f62134c93c7e4ffb492edf767f763 Mon Sep 17 00:00:00 2001
From: Bauke <me@bauke.xyz>
Date: Sun, 2 Jul 2023 12:04:29 +0200
Subject: [PATCH] Add documentation.

---
 source/tours/exports.ts                    |  1 +
 source/tours/shared/logged-out-warning.tsx |  1 +
 source/tours/shared/tour-error.tsx         |  4 ++++
 source/tours/types.ts                      | 28 ++++++++++++++++++++++
 source/tours/utilities.ts                  |  2 +-
 5 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/source/tours/exports.ts b/source/tours/exports.ts
index 9c25b24..8441070 100644
--- a/source/tours/exports.ts
+++ b/source/tours/exports.ts
@@ -6,6 +6,7 @@ export * from "./introduction.js";
 export * from "./shared/exports.js";
 export * from "./types.js";
 
+/** All tours available in a single array. */
 export const allTours: TourData[] = [
   introductionTour,
   accountSettingsTour,
diff --git a/source/tours/shared/logged-out-warning.tsx b/source/tours/shared/logged-out-warning.tsx
index 9717f82..81cb44c 100644
--- a/source/tours/shared/logged-out-warning.tsx
+++ b/source/tours/shared/logged-out-warning.tsx
@@ -1,5 +1,6 @@
 import {type JSX} from "preact";
 
+/** Check if the user is logged in and return a warning element if they aren't. */
 export function LoggedOutWarning(): JSX.Element {
   const userIsLoggedIn =
     document.querySelector(".logged-in-user-username") !== null;
diff --git a/source/tours/shared/tour-error.tsx b/source/tours/shared/tour-error.tsx
index 0f9bcb6..e4ad4be 100644
--- a/source/tours/shared/tour-error.tsx
+++ b/source/tours/shared/tour-error.tsx
@@ -1,6 +1,10 @@
 import Shepherd from "shepherd.js";
 import {renderInContainer} from "../utilities.js";
 
+/**
+ * Start an ad-hoc tour to display an error message.
+ * @param text The message to show.
+ */
 export function showTourError(text: string) {
   const tour = new Shepherd.Tour({
     defaultStepOptions: {
diff --git a/source/tours/types.ts b/source/tours/types.ts
index 2702204..b6e6ff5 100644
--- a/source/tours/types.ts
+++ b/source/tours/types.ts
@@ -1,30 +1,58 @@
 import type Shepherd from "shepherd.js";
 
+/** All available tour IDs. */
 export enum TourId {
   InterfaceAccountSettings = "interface-account-settings",
   InterfaceHomepage = "interface-homepage",
   Introduction = "introduction",
 }
 
+/** Requirements of a tour to be checked before the tour is started. */
 export type TourRequirement = {
+  /**
+   * This tour requires that the user must be logged in. Only set this to true
+   * if the tour goes to pages only accessible by logged in users.
+   */
   mustBeLoggedIn: boolean;
+
+  /** The {@link URL.pathname} to run the tour at. */
   path: string;
 };
 
+/** An individual tour step event handler. */
 export type TourStepEvent = {
+  /**
+   * - The "show" event will be called when the step is displayed.
+   * - The "destroy" event will be called when the step is finished.
+   */
   event: "show" | "destroy";
+  /** The handler for this step event. */
   handler: Parameters<Shepherd.Step["on"]>[1];
 };
 
+/** All the tour data collected in one place. */
 export type TourData = {
+  /** A short description of the tour for use in the options page. */
   description: string;
+
+  /** Whether this tour should be shown in the options page. */
   displayInOptionsPage: boolean;
+
+  /** All event handlers to be added to this tour's steps. */
   eventHandlers: Array<{
     eventHandlers: TourStepEvent[];
     stepId: string;
   }>;
+
+  /**  The unique ID for this tour. */
   id: TourId;
+
+  /** The requirements this tour must match before starting it. */
   requirements: TourRequirement;
+
+  /** All the steps this tour will take. */
   steps: Shepherd.Step.StepOptions[];
+
+  /** The title of the tour for use in the options page. */
   title: string;
 };
diff --git a/source/tours/utilities.ts b/source/tours/utilities.ts
index 331f009..2735936 100644
--- a/source/tours/utilities.ts
+++ b/source/tours/utilities.ts
@@ -5,7 +5,7 @@ import browser from "webextension-polyfill";
  * Adds a `[data-tildes-shepherd-counter]` attribute to a specified element. For
  * the associated CSS, see `source/content-scripts/scss/main.scss`.
  *
- * @param selector The selector of element to apply the counter to, if the
+ * @param selector The selector of the element to apply the counter to, if the
  * target element can't be selected an error will be thrown.
  * @param count The number to display in the counter.
  */