docs: Add file description and warning

coder · Parkreiner · Sep 15, 2023 · Sep 13, 2023 · Sep 13, 2023 · Sep 14, 2023
commit 83c6022265ebdded392de04d9b7c39cc3d137c64
diff --git a/site/src/hooks/debounce.ts b/site/src/hooks/debounce.ts
@@ -1,3 +1,16 @@
+/**
+ * @file Defines hooks for created debounced versions of functions and arbitrary
+ * values.
+ *
+ * It is not safe to call a general-purpose debounce utility inside a React
+ * render. It will work on the initial render, but the memory reference for the
+ * value will change on re-renders. Most debounce functions create a "stateful"
+ * version of a function by leveraging closure; but by calling it repeatedly,
+ * you create multiple "pockets" of state, rather than a centralized one.
+ *
+ * Debounce utilities can make sense if they can be called directly outside the
+ * component or in a useEffect call, though.
+ */
 import { useCallback, useEffect, useRef, useState } from "react";
 
 type useDebouncedFunctionReturn<Args extends unknown[]> = Readonly<{