More doc strings

Author: pokey

packages/cursorless-engine/src/DefaultSpokenFormMap.ts

@@ -12,6 +12,13 @@ type DefaultSpokenFormMapDefinition = {
   >;
 };
 
+/**
+ * This map contains the default spoken forms for all our speakable entities,
+ * including scope types, paired delimiters, etc. We would like this map to
+ * become the sole source of truth for our default spoken forms, including the
+ * Talon side. Today it is only used on the extension side for testing, and as a
+ * fallback when we can't get the custom spoken forms from Talon.
+ */
 const defaultSpokenFormMapCore: DefaultSpokenFormMapDefinition = {
   pairedDelimiter: {
     curlyBrackets: "curly",
@@ -130,6 +137,14 @@ const defaultSpokenFormMapCore: DefaultSpokenFormMapDefinition = {
   customRegex: {},
 };
 
+/**
+ * Used to construct entities that should not be speakable by default.
+ *
+ * @param spokenForms The default spoken forms for this entity
+ * @returns A DefaultSpokenFormMapEntry with the given spoken forms, and
+ * {@link DefaultSpokenFormMapEntry.isDisabledByDefault|isDisabledByDefault} set
+ * to true
+ */
 function disabledByDefault(
   ...spokenForms: string[]
 ): DefaultSpokenFormMapEntry {
@@ -140,6 +155,14 @@ function disabledByDefault(
   };
 }
 
+/**
+ * Used to construct entities that are only for internal experimentation.
+ *
+ * @param spokenForms The default spoken forms for this entity
+ * @returns A DefaultSpokenFormMapEntry with the given spoken forms, and
+ * {@link DefaultSpokenFormMapEntry.isDisabledByDefault|isDisabledByDefault} and
+ * {@link DefaultSpokenFormMapEntry.isSecret|isSecret} set to true
+ */
 function secret(...spokenForms: string[]): DefaultSpokenFormMapEntry {
   return {
     defaultSpokenForms: spokenForms,
@@ -150,7 +173,18 @@ function secret(...spokenForms: string[]): DefaultSpokenFormMapEntry {
 
 export interface DefaultSpokenFormMapEntry {
   defaultSpokenForms: string[];
+
+  /**
+   * If `true`, indicates that the entry may have a default spoken form, but
+   * it should not be enabled by default. These will show up in user csv's with
+   * a `-` at the beginning.
+   */
   isDisabledByDefault: boolean;
+
+  /**
+   * If `true`, indicates that the entry is only for internal experimentation,
+   * and should not be exposed to users except within a targeted working group.
+   */
   isSecret: boolean;
 }