diff --git a/example/plyr-example/src/App.jsx b/example/plyr-example/src/App.jsx
index b9e98466..eaba3084 100644
--- a/example/plyr-example/src/App.jsx
+++ b/example/plyr-example/src/App.jsx
@@ -14,6 +14,11 @@ const youtubeVideoSrc = {
   ],
 };
 
+/**
+ * Root React component that renders a heading and a Plyr video player configured with `youtubeVideoSrc`.
+ *
+ * @returns {JSX.Element} The app UI containing a header and the Plyr player.
+ */
 function App() {
   const ref = useRef(null);
 
diff --git a/src/index.tsx b/src/index.tsx
index c3411dde..1f78b977 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -71,6 +71,19 @@ const getAPI: GetAPI<PlyrInstance, PlyrConfigurationProps> = (
   });
 };
 
+/**
+ * Connects a video element ref to a Plyr instance and exposes a forwarded API ref.
+ *
+ * Initializes and manages the Plyr lifecycle using the provided `params`. The returned ref
+ * should be attached to the underlying <video> element; the forwarded `ref` receives an
+ * API object (shape: { plyr: PlyrInstance }) that is safe to use from parent components.
+ *
+ * @param params - Configuration for the Plyr instance: `source` (media source or null) and
+ *   `options` (Plyr options or null). Changes to these values will reconfigure the player.
+ * @param deps - Optional dependency list controlling when the underlying aptor logic runs.
+ *   If `null`, defaults to [params.options, params.source].
+ * @returns A ref to attach to the <video> element that Plyr will control.
+ */
 export function usePlyr(
   ref: Ref<APITypes>,
   params: PlyrConfigurationProps,