Add documentation

Author: AwdeDarkar

src/App.tsx

@@ -5,7 +5,9 @@ import TimerPage from "./TimerPage"
 import "./App.css"
 
 /**
+ * The main app component.
  *
+ * @returns {Element} The main app component.
  */
 export default function App() {
     return (

src/Timer.tsx

@@ -21,15 +21,24 @@ import {
 } from "./svgTools"
 
 /**
+ * Timer component.
  *
- * @param props
- * @param props.id
- * @param props.currentTime
- * @param props.triggerStart
- * @param props.triggerStop
- * @param props.onDelete
- * @param props.notifyWhenFinished
- * @param props.siblingRunning
+ * This is the main component for the timer page, it represents a countdown timer
+ * that may have children timers and enforces some rules about its children.
+ *
+ * @param {any} props Component props
+ * @param {UUID} props.id
+ *  The ID of the timer to display (used to lookup the timer data from local storage)
+ * @param {DateTime} props.currentTime The current time (used to calculate the time remaining)
+ * @param {Function} props.triggerStart Callback to inform the parent that the timer has started
+ * @param {Function} props.triggerStop Callback to inform the parent that the timer has paused
+ * @param {Function} props.onDelete Callback to inform the parent that the timer has been deleted
+ * @param {boolean} props.notifyWhenFinished Whether to notify the user when the timer finishes
+ * @param {UUID} props.siblingRunning
+ *  The ID of the sibling timer that is currently running (may be this timer,
+ *  or a non-existent timer). Used to enforce the rule that only one timer at a level
+ *  can be running at a time.
+ * @returns {Element} The timer component
  */
 export default function Timer(props: {
         id: UUID,
@@ -48,10 +57,17 @@ export default function Timer(props: {
     } = props
 
     /**
+     * This is a custom hook to manage the state of the timer and synchronize it
+     * with local storage by UUID. It is a wrapper around useLocalStorage and
+     * saves values in the format `<uuid>-<stateName>`.
      *
-     * @param stateName
-     * @param defaultValue
-     * @param serializer
+     * @template T The type of the state to manage
+     * @param {string} stateName The name of the state to manage (used as a suffix for the key)
+     * @param {T} defaultValue The default value to use if the state is not found in local storage
+     * @param {CustomSerializable} serializer
+     *  Serializer to correctly manage the state in local storage
+     * @returns {[T, (newValue: T) => void, () => void]}
+     *  The state value, a function to update the state, and a function to reset the state
      */
     function useUUIDStore<T>(
         stateName: string,
@@ -61,16 +77,19 @@ export default function Timer(props: {
         return useLocalStorage<T>(`${id}-${stateName}`, defaultValue, serializer)
     }
 
+    // TODO: setName and setTotalTime are unused, they'll be put in the edit dialog
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const [name, setName, clearName] = useUUIDStore<string>("name", "unnamed")
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const [totalTime, setTotalTime, clearTotalTime] = useUUIDStore<Duration>("totalTime", Duration.fromMillis(0), durationSerializer)
-    const [parentID, setParentID, clearParentID] = useUUIDStore<UUID|"root">("parentID", "root")
     const [childrenIDs, setChildrenIDs, clearChildrenIDs] = useUUIDStore<UUID[]>("childrenIDs", [])
 
     const [childRunning, setChildRunning, clearChildRunning] = useUUIDStore<UUID | undefined>("childRunning", undefined)
     const [started, setStarted, clearStarted] = useUUIDStore<DateTime | undefined>("started", undefined, datetimeMaybeSerializer)
     const [finished, setFinished, clearFinished] = useUUIDStore<boolean>("finished", false)
     const [elapsed, setElapsed, clearElapsed] = useUUIDStore<Duration>("elapsed", Duration.fromMillis(0), durationSerializer)
 
+    // These are the states that are not saved to local storage
     const [expanded, setExpanded] = useState<boolean>(false)
     const [addDialogOpen, setAddDialogOpen] = useState<boolean>(false)
 
@@ -79,10 +98,11 @@ export default function Timer(props: {
         setChildrenIDs([...childrenIDs, timer.id])
     }
 
+    // This function cleans up storage on deletion, though it's a bit messy and
+    // could probably be improved to more easily support adding new states
     const clearSelf = () => {
         clearName()
         clearTotalTime()
-        clearParentID()
         clearChildrenIDs()
         clearChildRunning()
         clearStarted()
@@ -236,14 +256,17 @@ export default function Timer(props: {
 }
 
 /**
+ * Custom start/pause control for timers that indecates the percent of time remaining
  *
- * @param props
- * @param props.running
- * @param props.finished
- * @param props.startable
- * @param props.percentRemaining
- * @param props.onStart
- * @param props.onStop
+ * @param {any} props Component props
+ * @param {boolean} props.running Whether the timer is currently running
+ * @param {boolean} props.finished Whether the timer has finished
+ * @param {boolean} props.startable
+ *  Whether the timer can be started (parent timers can't be started if all their time is allocated)
+ * @param {number} props.percentRemaining The percent of time remaining (0-1)
+ * @param {Function} props.onStart Callback to start the timer
+ * @param {Function} props.onStop Callback to pause the timer
+ * @returns {Element} The component
  */
 function TimerControl(props: {
         running: boolean, finished: boolean, startable: boolean,

src/TimerDialogs.tsx

@@ -7,12 +7,15 @@ import { uuidv4 } from "./uuid"
 import { TimerData } from "./timerUtils"
 
 /**
+ * Component form dialog for adding a new timer
  *
- * @param props
- * @param props.maxDuration
- * @param props.parentID
- * @param props.addTimer
- * @param props.onCancel
+ * @param {any} props Component props
+ * @param {Duration?} props.maxDuration
+ *  The maximum duration that can be set on this timer (by parent)
+ * @param {UUID} props.parentID The ID of the parent timer (if any)
+ * @param {Function} props.addTimer Callback to add a timer to the page
+ * @param {Function} props.onCancel Callback to cancel the timer creation
+ * @returns {Element} A JSX element for the timer creation dialog
  */
 export function AddTimerDialog(props: {
         maxDuration?: Duration,
@@ -82,10 +85,12 @@ export function AddTimerDialog(props: {
 }
 
 /**
+ * Component with a custom hours:minutes:seconds duration input
  *
- * @param props
- * @param props.onChange
- * @param props.maxDuration
+ * @param {any} props Component props
+ * @param {Function} props.onChange Callback to call when the duration changes
+ * @param {Duration} props.maxDuration The maximum duration that can be set (by parent, if any)
+ * @returns {Element} A JSX element for the duration input
  */
 export function DurationInput(props: {
         onChange: (time: {hours: number, minutes: number, seconds: number}) => void,

src/TimerPage.tsx

@@ -13,19 +13,27 @@ import { AddTimerDialog } from "./TimerDialogs"
 import Timer from "./Timer"
 
 /**
+ * The main page of the app, which displays all the root timers in a list.
  *
+ * @returns {Element} The main page of the app.
  */
 export default function TimerPage(props: {}) {
     /**
+     * This is a custom hook to manage the state of the root timers and synchronize
+     * them with local storage. Values are saved with the key `root-<stateName>`.
      *
-     * @param stateName
-     * @param defaultValue
+     * @template T The type of the state to manage
+     * @param {string} stateName The name of the state to manage
+     * @param {T} defaultValue The default value of the state
+     * @returns {[T, (value: T) => void, () => void]}
+     *  The state value, a function to set the state value, and a function to reset it
      */
     function usePageStore<T>(stateName: string, defaultValue: T):
     [T, (newValue: T) => void, () => void] {
         return useLocalStorage<T>(`root-${stateName}`, defaultValue)
     }
 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const [timerIDs, setTimerIDs, _] = usePageStore<UUID[]>("timers", [])
     const [addDialogOpen, setAddDialogOpen] = useState<boolean>(false)
     const [currentTime, setCurrentTime] = useState<DateTime>(DateTime.local())

src/localStorageTools.ts

@@ -1,31 +1,76 @@
 import { useState } from "react"
 import { DateTime, Duration } from "luxon"
 
+/**
+ * CustomSerializable is a generic type that can provide serialization/deserialization
+ * for any type to allow it to be reliably stored in localStorage.
+ *
+ * @interface
+ */
 export interface CustomSerializable<T> {
+    /**
+     * serialize is a function that takes a value of type T and returns a string
+     *
+     * @template T
+     * @param {T} value
+     * @returns {string}
+     * @memberof CustomSerializable
+     */
     stringify: (value: T) => string
+
+    /**
+     * deserialize is a function that takes a string and returns a value of type T
+     *
+     * @template T
+     * @param {string} value
+     * @returns {T}
+     * @memberof CustomSerializable
+     */
     parse: (value: string) => T
 }
 
+/**
+ * The defaultSerializer is a CustomSerializable that uses JSON.stringify and JSON.parse,
+ * but it also wraps strings in quotes to ensure that they are stored as strings in localStorage
+ * and can be retrieved as strings.
+ *
+ * @implements {CustomSerializable<any>}
+ */
 export const defaultSerializer: CustomSerializable<any> = {
     stringify: (value: any) => ((typeof value === "string") ? `"${value}"` : JSON.stringify(value)),
     parse: (value: string) => JSON.parse(value),
 }
 
+/**
+ * The datetimeMaybeSerializer is a CustomSerializable that stores Luxon DateTime objects
+ * as strings in ISO format, but also stores undefined values as the string "undefined".
+ *
+ * @implements {CustomSerializable<DateTime | undefined>}
+ */
 export const datetimeMaybeSerializer: CustomSerializable<DateTime | undefined> = {
     stringify: (value: DateTime | undefined) => ((value === undefined) ? "\"undefined\"" : value.toISO()),
     parse: (value: string) => ((value === "\"undefined\"") ? undefined : DateTime.fromISO(value)),
 }
 
+/**
+ * The durationSerializer is a CustomSerializable that stores Luxon Duration objects
+ * as milliseconds.
+ *
+ * @implements {CustomSerializable<Duration>}
+ */
 export const durationSerializer: CustomSerializable<Duration> = {
     stringify: (value: Duration) => value.shiftTo("milliseconds").milliseconds.toString(),
     parse: (value: string) => Duration.fromMillis(parseInt(value, 10)).shiftTo("hours", "minutes", "seconds"),
 }
 
 /**
  *
- * @param storageKey
- * @param defaultValue
- * @param serialization
+ * @template T
+ * @param {string} storageKey The key to use for localStorage
+ * @param {T} defaultValue The default value to use if the key is not found in localStorage
+ * @param {CustomSerializable<T>} serialization The serialization method to use for the value
+ * @returns {[T, (value: T) => void, () => void]}
+ *  The state value, a function to set the state value, and a function to reset it
  */
 export function useLocalStorage<T>(
     storageKey: string,
@@ -41,6 +86,8 @@ export function useLocalStorage<T>(
         return defaultValue
     })
 
+    // Note for future self: we can't useEffect here because it will cause an infinite loop
+
     const updateValue = (newValue: T) => {
         setValue(newValue)
         localStorage.setItem(storageKey, serialization.stringify(newValue))