Merge pull request #1058 from chintan9/update-jsdocs

add more jsdocs

Author: chintan9

dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plyr-react",
-  "version": "5.1.2",
+  "version": "5.2.0",
   "private": false,
   "description": "A simple HTML5, YouTube and Vimeo player for react using plyr",
   "keywords": [

example/nextjs/pages/_app.js

@@ -1,5 +1,9 @@
 import "../styles/globals.css";
 
+/**
+ * This is a functional component in JavaScript that returns a component with its props.
+ * @returns The function `MyApp` is returning the `Component` with the `pageProps` passed as props.
+ */
 function MyApp({ Component, pageProps }) {
   return <Component {...pageProps} />;
 }

example/nextjs/pages/index.js

@@ -2,6 +2,11 @@ import dynamic from "next/dynamic";
 
 const VideoList = dynamic(() => import("../src/video-list"), { ssr: false });
 
+/**
+ * The function returns a component that displays a heading and a list of videos.
+ * @returns The `Home` component is being returned, which contains a `div` element with a heading
+ * "Video List" and a `VideoList` component.
+ */
 export default function Home() {
   return (
     <div>

example/nextjs/src/video-list.jsx

@@ -2,6 +2,11 @@ import Plyr from "plyr-react";
 import "plyr-react/dist/plyr.css";
 import contents from "./contents.json";
 
+/**
+ * This code exports a React component called `VideoList` that renders a list of videos using the Plyr
+video player.
+ * @returns Plyr instance
+ */
 export default function VideoList() {
   return (
     <ul className="video-list">

example/react/src/audio-player/custom-audio-player.tsx

@@ -4,6 +4,7 @@ import "plyr-react/dist/plyr.css";
 
 const videoOptions = undefined;
 
+/* This object is used as the source for the `CustomPlyrInstance` component. */
 const videoSource = {
   type: "audio" as const,
   sources: [
@@ -14,6 +15,9 @@ const videoSource = {
   ],
 };
 
+/* This code defines a custom React component called `CustomPlyrInstance` that uses the
+`React.forwardRef` function to forward a ref to a child component. The component takes in two props:
+`source` and `options`, which are used to configure the Plyr instance. */
 const CustomPlyrInstance = React.forwardRef<APITypes, PlyrProps>(
   (props, ref) => {
     const { source, options = null } = props;
@@ -29,6 +33,7 @@ const CustomPlyrInstance = React.forwardRef<APITypes, PlyrProps>(
       const { current } = ref as React.MutableRefObject<APITypes>;
       if (current.plyr.source === null) return;
 
+      /* This code is accessing the Plyr instance API and adding event listeners to it. */
       const api = current as { plyr: PlyrInstance };
       api.plyr.on("ready", () => console.log("I'm ready"));
       api.plyr.on("canplay", () => {
@@ -48,6 +53,9 @@ const CustomPlyrInstance = React.forwardRef<APITypes, PlyrProps>(
   }
 );
 
+/* This code defines a functional component called `PlyrComponent` that renders a `CustomPlyrInstance`
+component with a `ref` and `source` and `options` props. The`source` and `options` props are used to 
+configure the Plyr instance. The component is wrapped in a `div` with a class name of "wrapper". */
 const PlyrComponent = () => {
   const ref = React.useRef<APITypes>(null);
 

example/react/src/hls-player/custom-hls-player.tsx

@@ -8,6 +8,17 @@ const videoOptions = null;
 const videoSource = null;
 const hlsSource = "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8";
 
+/**
+ * This is a custom hook in TypeScript React that loads and attaches an HLS video source to a Plyr
+ * player, and sets the quality options for the player.
+ * @param {string} src - The source URL of the video that will be played.
+ * @param {Options | null} options - `options` is an object that contains optional configuration
+ * options for the Plyr player. It can include properties such as `autoplay`, `controls`, `loop`,
+ * `muted`, `seekTime`, `volume`, and more. This parameter is optional and can be `null`.
+ * @returns The `useHls` function returns an object with a single property `options`, which is of type
+ * `Options | null`. The `options` object contains information about the video quality and any other
+ * custom event listeners that may have been added.
+ */
 const useHls = (src: string, options: Options | null) => {
   const hls = React.useRef<Hls>(new Hls());
   const hasQuality = React.useRef<boolean>(false);
@@ -37,6 +48,9 @@ const useHls = (src: string, options: Options | null) => {
         default: levels[levels.length - 1].height,
         options: levels.map((level) => level.height),
         forced: true,
+        /* `onChange` is a callback function that gets triggered when the user changes the quality of
+       the video. It takes in a `newQuality` parameter which is the new quality selected by the
+       user. */
         onChange: (newQuality: number) => {
           console.log("changes", newQuality);
           levels.forEach((level, levelIndex) => {
@@ -54,6 +68,9 @@ const useHls = (src: string, options: Options | null) => {
   return { options: plyrOptions };
 };
 
+/** `CustomPlyrInstance` is a custom React component that renders a video player using the Plyr library
+and supports HLS video streaming. It is created using the `React.forwardRef` function, which allows
+the component to receive a `ref` to the player instance as a prop. */
 const CustomPlyrInstance = React.forwardRef<
   APITypes,
   PlyrProps & { hlsSource: string }
@@ -66,13 +83,18 @@ const CustomPlyrInstance = React.forwardRef<
   return <video ref={raptorRef} className="plyr-react plyr" />;
 });
 
+/**  The `PlyrComponent` is a functional component that renders a video player using the Plyr library and
+supports HLS video streaming. If it is supported, it renders the `CustomPlyrInstance` component passing in the `ref`,
+`source`, `options`, and `hlsSource` props. If HLS is not supported, it renders a message saying so. */
 const PlyrComponent = () => {
   const ref = React.useRef<APITypes>(null);
   const supported = Hls.isSupported();
 
   return (
     <div className="wrapper">
       {supported ? (
+        /**  `<CustomPlyrInstance>` is a custom React component that renders a video player using the
+        Plyr library and supports HLS video streaming. It takes in several props: */
         <CustomPlyrInstance
           ref={ref}
           source={videoSource}

example/react/src/video-list/video-list.tsx

@@ -2,6 +2,11 @@ import Plyr from "plyr-react";
 import "plyr-react/dist/plyr.css";
 import contents from "./contents.json";
 
+/**
+ * This code exports a React component called `VideoList` that renders a list of videos using the Plyr
+video player.
+ * @returns Plyr instance
+ */
 export default function VideoList() {
   return (
     <ul className="video-list">