useAuthorizedData と useCustomizedSWR のドキュメントを改善する (#617)

Author: aster-void

web/hooks/useCustomizedSWR.ts

@@ -39,8 +39,31 @@ export type Hook<T> = {
 const SWR_PREFIX = "CourseMate::useSWR::";
 // todo: consider using useSWR Hook from external instead.
 /**
- use static function instead of inline arrow function
- to prevent unnecessary useCallback calls.
+  DANGER: `schema` や `fetcher` は *絶対に* inline で書いてはいけない。
+  inline で書くと、無限描画ループに陥る。
+  例:
+  ```javascript
+  // BAD
+  function Component() {
+    const data = useCustomizedSWR(
+      "myUniqueKey",
+      () => fetch("/path"), // ✘
+      z.array(z.number()), // ✘
+    );
+  }
+  // GOOD
+  const fetcher = () => fetch("/path");
+  const schema = z.array(z.number());
+
+  function Component() {
+    const data = useCustomizedSWR(
+      "myUniqueKey",
+      fetcher, // ◯
+      schema, // ◯
+    );
+  }
+  ```
+
  cacheKey **MUST** be unique in all the codebase, otherwise the cache will interfere each other.
  (I recommend using URL Path, friend's name + unique prefix, or randomly generate static string.)
  **/

web/hooks/useData.ts

@@ -51,6 +51,23 @@ async function safeReadData<T>(
 }
 
 // TODO: refactor this to look better.
+/**
+  DANGER: `schema` は *絶対に* inline で書いてはいけない。
+  inline で書くと、無限描画ループに陥る。
+  例:
+  ```javascript
+  // BAD
+  function Component() {
+    const data = useAuthorizedData("/path", z.array(z.number()));
+  }
+  // GOOD
+  const schema = z.array(z.number());
+
+  function Component() {
+    const data = useAuthorizedData("/path", schema);
+  }
+  ```
+ */
 export function useAuthorizedData<T>(url: string, schema: Zod.Schema<T>) {
   const [data, setData] = useState<T | null>(null);
   const [loading, setLoading] = useState<boolean>(false);