Use TS-flavored doc comments

Nate Butler created 2 years ago

Change summary

styles/src/styleTree/interactive.ts | 54 ++++++++++++++++-----------
styles/src/styleTree/toggle.ts      | 60 +++++++++++++++++-------------
2 files changed, 64 insertions(+), 50 deletions(-)

Detailed changes

styles/src/styleTree/interactive.ts

@@ -1,33 +1,41 @@
 import { DeepPartial } from "utility-types";
 import merge from "ts-deepmerge"
 interface Interactive<T> {
-  default: T,
-  hover?: T,
-  clicked?: T,
-  disabled?: T,
+    default: T,
+    hover?: T,
+    clicked?: T,
+    disabled?: T,
 }
 
-// Helper function for creating Interactive<T> objects that works pretty much like Toggle<T>.
-// It takes a object to be used as a value for `default` field and then fills out other fields
-// with fields from either `base` or `modifications`. Notably, it does not touch `hover`, `clicked` and `disabled` if there are no modifications for it.
+/**
+ * Helper function for creating Interactive<T> objects that works pretty much like Toggle<T>.
+ * It takes a object to be used as a value for `default` field and then fills out other fields
+ * with fields from either `base` or `modifications`.
+ * Notably, it does not touch `hover`, `clicked` and `disabled` if there are no modifications for it.
+ *
+ * @param defaultObj Object to be used as the value for `default` field.
+ * @param base Object containing base fields to be included in the resulting object.
+ * @param modifications Object containing modified fields to be included in the resulting object.
+ * @returns Interactive<T> object with fields from `base` and `modifications`.
+ */
 export function interactive<T extends Object>(base: T, modifications: DeepPartial<Interactive<T>>): Interactive<T> {
-  let interactiveObj: Interactive<T> = {
-    default: base,
-  };
-  if (modifications.default !== undefined) {
-    interactiveObj.default = merge(interactiveObj.default, modifications.default) as T;
-  }
-  if (modifications.hover !== undefined) {
-    interactiveObj.hover = merge(interactiveObj.default, modifications.hover) as T;
-  }
+    let interactiveObj: Interactive<T> = {
+        default: base,
+    };
+    if (modifications.default !== undefined) {
+        interactiveObj.default = merge(interactiveObj.default, modifications.default) as T;
+    }
+    if (modifications.hover !== undefined) {
+        interactiveObj.hover = merge(interactiveObj.default, modifications.hover) as T;
+    }
 
-  if (modifications.clicked !== undefined) {
-    interactiveObj.clicked = merge(interactiveObj.default, modifications.clicked) as T;
-  }
+    if (modifications.clicked !== undefined) {
+        interactiveObj.clicked = merge(interactiveObj.default, modifications.clicked) as T;
+    }
 
-  if (modifications.disabled !== undefined) {
-    interactiveObj.disabled = merge(interactiveObj.default, modifications.disabled) as T;
-  }
+    if (modifications.disabled !== undefined) {
+        interactiveObj.disabled = merge(interactiveObj.default, modifications.disabled) as T;
+    }
 
-  return interactiveObj;
+    return interactiveObj;
 }

styles/src/styleTree/toggle.ts

@@ -2,34 +2,40 @@ import { DeepPartial } from 'utility-types';
 import merge from 'ts-deepmerge';
 
 interface Toggleable<T> {
-  inactive: T
-  active: T,
+    inactive: T
+    active: T,
 }
 
-/// Helper function for creating Toggleable objects; it takes a object of type T that is used as
-/// `inactive` member of result Toggleable<T>. `active` member is created by applying `modifications` on top of `inactive` argument.
-// Thus, the following call:
-// ```
-//   toggleable({day: 1, month: "January"}, {day: 3})
-// ```
-// To return the following object:
-// ```
-//    Toggleable<_>{
-//      inactive: { day: 1, month: "January" },
-//      active: { day: 3, month: "January" }
-//    }
-// ```
-// Remarkably, it also works for nested structures:
-// ```
-//   toggleable({first_level: "foo", second_level: {nested_member: "nested"}}, {second_level: {nested_member: "another nested thing"}})
-// ```
-// ```
-//   Toggleable<_> {
-//     inactive: {first_level: "foo", second_level: {nested_member: "nested"}},
-//     active: { first_level: "foo", second_level: {nested_member: "another nested thing"}}
-//   }
-// ```
+/**
+ * Helper function for creating Toggleable objects.
+ * @template T The type of the object being toggled.
+ * @param inactive The initial state of the toggleable object.
+ * @param modifications The modifications to be applied to the initial state to create the active state.
+ * @returns A Toggleable object containing both the inactive and active states.
+ * @example
+ * ```
+ * toggleable({day: 1, month: "January"}, {day: 3})
+ * ```
+ * This returns the following object:
+ * ```
+ *  Toggleable<_>{
+ *    inactive: { day: 1, month: "January" },
+ *    active: { day: 3, month: "January" }
+ *  }
+ * ```
+ * The function also works for nested structures:
+ * ```
+ *   toggleable({first_level: "foo", second_level: {nested_member: "nested"}}, {second_level: {nested_member: "another nested thing"}})
+ * ```
+ * Which returns:
+ * ```
+ *   Toggleable<_> {
+ *     inactive: {first_level: "foo", second_level: {nested_member: "nested"}},
+ *     active: { first_level: "foo", second_level: {nested_member: "another nested thing"}}
+ *   }
+ * ```
+ */
 export function toggleable<T extends Object>(inactive: T, modifications: DeepPartial<T>): Toggleable<T> {
-  let active: T = merge(inactive, modifications) as T;
-  return { active: active, inactive: inactive };
+    let active: T = merge(inactive, modifications) as T;
+    return { active: active, inactive: inactive };
 }