Colin the Code Commentor: Suggested comment improvements

Author: dsyme

src/main.ts

@@ -12,7 +12,11 @@ import { UnrealBloomPass } from "three/examples/jsm/postprocessing/UnrealBloomPa
 // Set up the scene
 const scene = new THREE.Scene();
 
-// Create atmospheric space background
+/**
+ * Create atmospheric space background as a large sphere with a nebula-like gradient and subtle star effects.
+ * @returns background mesh to be added to the scene
+ */
+
 function createSpaceBackground() {
   // Create background geometry - a large sphere that encompasses the scene
   const backgroundGeometry = new THREE.SphereGeometry(500, 32, 16);
@@ -112,7 +116,11 @@ function createSpaceBackground() {
 const spaceBackground = createSpaceBackground();
 scene.add(spaceBackground);
 
-// Calculate responsive field of view based on screen size
+/**
+ * Calculate responsive field of view based on screen size
+ * @returns the calculated field of view value adjusted for screen dimensions
+ */
+
 function getResponsiveFOV(): number {
   const minFOV = 60; // Current desktop FOV
   const maxFOV = 100; // Wider view for small screens to fit more content
@@ -126,7 +134,11 @@ function getResponsiveFOV(): number {
   return fov;
 }
 
-// Calculate responsive camera positions based on screen size
+/**
+ * Calculate responsive camera positions based on screen size
+ * @returns an object containing introZ and gameZ camera positions adjusted for screen width
+ */
+
 function getResponsiveCameraPositions() {
   const minIntroZ = 3.0; // Current desktop intro position
   const maxIntroZ = 4.0; // Further back for mobile
@@ -185,7 +197,12 @@ const composer = new EffectComposer(renderer);
 const renderPass = new RenderPass(scene, camera);
 composer.addPass(renderPass);
 
-// Calculate responsive pixel size based on screen size
+/**
+ * Calculate responsive pixel size based on screen width and height.
+ * Returns a pixel size that scales between a minimum and maximum value depending on screen dimensions.
+ * @returns responsive pixel size based on current screen size
+ */
+
 function getResponsivePixelSize(): number {
   const minPixelSize = 2.0; // Smaller pixels for mobile
   const maxPixelSize = 8.0; // Current desktop pixel size
@@ -199,7 +216,11 @@ function getResponsivePixelSize(): number {
   return pixelSize;
 }
 
-// Calculate responsive scanline size based on screen size
+/**
+ * Calculate responsive scanline size based on screen size.
+ * @returns the scanline size adjusted for the current screen dimensions.
+ */
+
 function getResponsiveScanlineSize(): number {
   const minScanlineSize = 2; // Thinner scanlines for mobile
   const maxScanlineSize = 5; // Current desktop scanline size
@@ -467,7 +488,10 @@ const crtOverlay = document.createElement("div");
 crtOverlay.className = "crt-overlay";
 document.body.appendChild(crtOverlay);
 
-// Function to update scanline size responsively
+/**
+ * Function to update the scanline size responsively by adjusting the background size of the CRT overlay element.
+ */
+
 function updateScanlineSize() {
   const scanlineSize = getResponsiveScanlineSize();
   if (crtOverlay) {
@@ -504,7 +528,10 @@ let musicGainNode: GainNode | null = null;
 let isMuted = false;
 let musicFadeTimeout: number | null = null; // Track fade timeout for cleanup
 
-// Load and decode the background music
+/**
+ * Load and decode the background music asynchronously.
+ */
+
 async function loadBackgroundMusic() {
   if (!audioContext) return;
 
@@ -517,7 +544,14 @@ async function loadBackgroundMusic() {
   }
 }
 
-// Start playing background music
+/**
+ * Start playing background music with fade-in and looping.
+ * Clears any pending fade timeout before starting.
+ * Creates gain node for volume control and sets initial volume to 0.
+ * Connects audio nodes and starts playback with looping enabled.
+ * Handles music end event to restart music if game is still running.
+ */
+
 function startBackgroundMusic() {
   if (!audioContext || !musicBuffer || backgroundMusic) return;
 
@@ -564,7 +598,12 @@ function startBackgroundMusic() {
   }
 }
 
-// Stop background music
+/**
+ * Stop background music with a fade out effect.
+ * Clears any pending fade timeout, fades out the music gain over 0.6 seconds,
+ * then stops and disconnects the background music and gain node.
+ */
+
 function stopBackgroundMusic() {
   if (!backgroundMusic || !musicGainNode || !audioContext) return;
 
@@ -613,7 +652,10 @@ function stopBackgroundMusic() {
   }
 }
 
-// Toggle mute state
+/**
+ * Toggle mute state and smoothly fade audio volume.
+ */
+
 function toggleMute() {
   isMuted = !isMuted;