From 594a7f2e4b8fe53a7b2156ddef1fb9b02f23f0b9 Mon Sep 17 00:00:00 2001 From: Chintan Prajapati Date: Mon, 17 Apr 2023 21:02:36 +0000 Subject: [PATCH] add more jsdocs --- dist/package.json | 2 +- example/nextjs/pages/_app.js | 4 ++++ example/nextjs/pages/index.js | 5 +++++ example/nextjs/src/video-list.jsx | 5 +++++ .../src/audio-player/custom-audio-player.tsx | 8 +++++++ .../src/hls-player/custom-hls-player.tsx | 22 +++++++++++++++++++ example/react/src/video-list/video-list.tsx | 5 +++++ 7 files changed, 50 insertions(+), 1 deletion(-) diff --git a/dist/package.json b/dist/package.json index d63f1cda..8e41c837 100644 --- a/dist/package.json +++ b/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": [ diff --git a/example/nextjs/pages/_app.js b/example/nextjs/pages/_app.js index 2fc3e070..940cc0fe 100644 --- a/example/nextjs/pages/_app.js +++ b/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 ; } diff --git a/example/nextjs/pages/index.js b/example/nextjs/pages/index.js index c7974831..b190d4b5 100644 --- a/example/nextjs/pages/index.js +++ b/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 (
diff --git a/example/nextjs/src/video-list.jsx b/example/nextjs/src/video-list.jsx index 034de6b6..64dd32c7 100644 --- a/example/nextjs/src/video-list.jsx +++ b/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 (
    diff --git a/example/react/src/audio-player/custom-audio-player.tsx b/example/react/src/audio-player/custom-audio-player.tsx index 11bbb840..7800b7e3 100644 --- a/example/react/src/audio-player/custom-audio-player.tsx +++ b/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( (props, ref) => { const { source, options = null } = props; @@ -29,6 +33,7 @@ const CustomPlyrInstance = React.forwardRef( const { current } = ref as React.MutableRefObject; 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( } ); +/* 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(null); diff --git a/example/react/src/hls-player/custom-hls-player.tsx b/example/react/src/hls-player/custom-hls-player.tsx index 2f4444c2..993c32aa 100644 --- a/example/react/src/hls-player/custom-hls-player.tsx +++ b/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(new Hls()); const hasQuality = React.useRef(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,6 +83,9 @@ const CustomPlyrInstance = React.forwardRef< return