From 189be570232e6068b2077d448d8dea49bf81b983 Mon Sep 17 00:00:00 2001
From: Chneemann <andre-kempf@mailbox.org>
Date: Sat, 26 Apr 2025 22:53:10 +0200
Subject: [PATCH] docs: add comments to functions in VideoPlayerComponent

---
 .../video-player/video-player.component.ts    | 57 +++++++++++++++++--
 1 file changed, 52 insertions(+), 5 deletions(-)

diff --git a/frontend/src/app/components/home/video-player/video-player.component.ts b/frontend/src/app/components/home/video-player/video-player.component.ts
index 93bde4f..a3b6ec4 100644
--- a/frontend/src/app/components/home/video-player/video-player.component.ts
+++ b/frontend/src/app/components/home/video-player/video-player.component.ts
@@ -5,16 +5,25 @@ import Hls from 'hls.js';
 @Component({
   selector: 'app-video-player',
   standalone: true,
+  imports: [],
   templateUrl: './video-player.component.html',
   styleUrls: ['./video-player.component.scss'],
 })
 export class VideoPlayerComponent implements OnInit, OnDestroy {
   @Input() playMovie: string = '';
+
   private hls: Hls | null = null;
   private videoElement: HTMLVideoElement | null = null;
   private resolutionUrls: { [key: string]: string } = {};
   private defaultResolution: string;
 
+  /**
+   * Creates a new instance of the VideoPlayerComponent and sets the default
+   * resolution by fetching it from the ResolutionService.
+   *
+   * @param elementRef A reference to the DOM element which hosts the video player.
+   * @param resolutionService A service which provides the available resolutions.
+   */
   constructor(
     private elementRef: ElementRef,
     private resolutionService: ResolutionService
@@ -22,14 +31,25 @@ export class VideoPlayerComponent implements OnInit, OnDestroy {
     this.defaultResolution = this.resolutionService.getDefaultResolution();
   }
 
+  /**
+   * Angular lifecycle hook: Called once the component is initialized.
+   * Initializes the video player with the default resolution.
+   */
   ngOnInit(): void {
     this.initializePlayer();
   }
 
+  /**
+   * Angular lifecycle hook: Called once the component is about to be destroyed.
+   * Cleans up HLS resources.
+   */
   ngOnDestroy(): void {
     this.hls?.destroy();
   }
 
+  /**
+   * Initializes the video player and loads the default resolution.
+   */
   private initializePlayer(): void {
     this.videoElement = this.elementRef.nativeElement.querySelector('video');
     if (!this.playMovie || !this.videoElement) return;
@@ -46,6 +66,10 @@ export class VideoPlayerComponent implements OnInit, OnDestroy {
     this.updateScreenDimensions();
   }
 
+  /**
+   * Generates a mapping of available resolutions to their respective URLs.
+   * @returns An object containing resolution-URL pairs.
+   */
   private getResolutionUrls(): { [key: string]: string } {
     return Object.fromEntries(
       this.resolutionService
@@ -54,6 +78,10 @@ export class VideoPlayerComponent implements OnInit, OnDestroy {
     );
   }
 
+  /**
+   * Initializes the video player using HLS.js if supported.
+   * @param url - The URL of the video stream to load.
+   */
   private initHlsPlayer(url: string): void {
     if (!this.videoElement) return;
     this.hls = new Hls();
@@ -62,6 +90,10 @@ export class VideoPlayerComponent implements OnInit, OnDestroy {
     this.hls.on(Hls.Events.MANIFEST_PARSED, () => this.videoElement?.play());
   }
 
+  /**
+   * Initializes the native HTML5 video player if HLS is natively supported.
+   * @param url - The URL of the video stream to load.
+   */
   private initNativePlayer(url: string): void {
     if (!this.videoElement) return;
     this.videoElement.src = url;
@@ -70,13 +102,19 @@ export class VideoPlayerComponent implements OnInit, OnDestroy {
     );
   }
 
+  /**
+   * Updates the video element's dimensions to match the window size.
+   */
   private updateScreenDimensions(): void {
-    if (this.videoElement) {
-      this.videoElement.style.width = `${window.innerWidth}px`;
-      this.videoElement.style.height = `${window.innerHeight}px`;
-    }
+    if (!this.videoElement) return;
+    this.videoElement.style.width = `${window.innerWidth}px`;
+    this.videoElement.style.height = `${window.innerHeight}px`;
   }
 
+  /**
+   * Switches the video resolution to the specified one, or falls back to the default resolution if not available.
+   * @param resolution - The desired resolution (e.g., '720p', '1080p').
+   */
   public switchResolution(resolution: string): void {
     const targetUrl =
       this.resolutionUrls[resolution] ||
@@ -90,12 +128,21 @@ export class VideoPlayerComponent implements OnInit, OnDestroy {
     }
   }
 
+  /**
+   * Loads a new video stream source using HLS.js.
+   * @param url - The URL of the new video stream.
+   */
   private loadHlsSource(url: string): void {
     this.hls?.loadSource(url);
     this.hls?.attachMedia(this.videoElement!);
   }
 
+  /**
+   * Loads a new video stream source using the native HTML5 player.
+   * @param url - The URL of the new video stream.
+   */
   private loadNativeSource(url: string): void {
-    if (this.videoElement) this.videoElement.src = url;
+    if (!this.videoElement) return;
+    this.videoElement.src = url;
   }
 }