From 6ef26ed8769aeefc61793a404d605ac178160032 Mon Sep 17 00:00:00 2001
From: Pokey Rule <755842+pokey@users.noreply.github.com>
Date: Fri, 20 Oct 2023 15:22:07 +0100
Subject: [PATCH] Doc strings

---
 packages/common/src/types/SpokenForm.ts | 34 +++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/packages/common/src/types/SpokenForm.ts b/packages/common/src/types/SpokenForm.ts
index 43934839214..f79e5d4a7a5 100644
--- a/packages/common/src/types/SpokenForm.ts
+++ b/packages/common/src/types/SpokenForm.ts
@@ -1,13 +1,47 @@
+/**
+ * The spoken form of a command, scope type, etc, that can be spoken
+ * using a given set of custom or default spoken forms.
+ */
 export interface SpokenFormSuccess {
   type: "success";
+
+  /**
+   * The spoken forms for this entity. These could either be a user's custom
+   * spoken forms, if we have access to them, or the default spoken forms, if we
+   * don't, or if we're testing. There will often only be a single entry in this
+   * array, but there can be multiple if the user has used the `|` syntax in their
+   * spoken form csv's to define aliases for a single spoken form.
+   */
   spokenForms: string[];
 }
 
+/**
+ * An error spoken form, which indicates that the given entity (command, scope
+ * type, etc) cannot be spoken, and the reason why.
+ */
 export interface SpokenFormError {
   type: "error";
+
+  /**
+   * The reason why the entity cannot be spoken.
+   */
   reason: string;
+
+  /**
+   * If `true`, indicates that the entity wasn't found in the user's Talon spoken
+   * forms json, and so they need to update their cursorless-talon to get the
+   * given entity.
+   */
   requiresTalonUpdate: boolean;
+
+  /**
+   * If `true`, indicates that the entity is only for internal experimentation,
+   * and should not be exposed to users except within a targeted working group.
+   */
   isPrivate: boolean;
 }
 
+/**
+ * A spoken form, which can either be a success or an error.
+ */
 export type SpokenForm = SpokenFormSuccess | SpokenFormError;