Improve JSDoc for Standard Material (#7532)

* Enhance JSDoc generation for standard material properties in rollup-types-fixup.mjs. Added a transformer function to dynamically generate property descriptions based on existing JSDoc comments, improving documentation accuracy.

* Refactor JSDoc generation in rollup-types-fixup.mjs to improve readability and maintainability. Streamlined the mapping of standard material properties and enhanced the cleaning of type descriptions for better documentation output.

* Remove commented-out console log in rollup-types-fixup.mjs to clean up code and enhance readability.

Author: marklundin

utils/plugins/rollup-types-fixup.mjs

@@ -191,12 +191,28 @@ const STANDARD_MAT_PROPS = [
 const REPLACEMENTS = [{
     path: `${TYPES_PATH}/scene/materials/standard-material.d.ts`,
     replacement: {
-        from: 'reset(): void;',
-        to: `reset(): void;
-${STANDARD_MAT_PROPS.map(prop => `
-    set ${prop[0]}(arg: ${prop[1]});
-    get ${prop[0]}(): ${prop[1]};
-`).join('')}`,
+        transformer: (contents) => {
+
+            // Find the jsdoc block description using eg "@property {Type} {name}"
+            return contents.replace('reset(): void;', `reset(): void;
+                ${STANDARD_MAT_PROPS.map((prop) => {
+        const typeDefinition = `@property {${prop[1]}} ${prop[0]}`;
+        const typeDescriptionIndex = contents.match(typeDefinition);
+        const typeDescription = typeDescriptionIndex ?
+            contents.slice(typeDescriptionIndex.index + typeDefinition.length, contents.indexOf('\n * @property', typeDescriptionIndex.index + typeDefinition.length)) :
+            '';
+
+        // Strip newlines, asterisks, and tabs from the type description
+        const cleanTypeDescription = typeDescription
+        .trim()
+        .replace(/[\n\t*]/g, ' ') // remove newlines, tabs, and asterisks
+        .replace(/\s+/g, ' '); // collapse whitespace
+
+        const jsdoc = cleanTypeDescription ? `/** ${cleanTypeDescription} */` : '';
+        return `\t${jsdoc}\n\tset ${prop[0]}(arg: ${prop[1]});\n\tget ${prop[0]}(): ${prop[1]};\n\n`;
+    }).join('')}`
+            );
+        },
         footer: `
 import { Color } from '../../core/math/color.js';
 import { Vec2 } from '../../core/math/vec2.js';
@@ -243,9 +259,13 @@ export function typesFixup() {
         name: 'types-fixup',
         buildStart() {
             REPLACEMENTS.forEach((item) => {
-                const { from, to, footer } = item.replacement;
+                const { from, to, footer, transformer } = item.replacement;
                 let contents = fs.readFileSync(item.path, 'utf-8');
-                contents = contents.replace(from, to);
+                if (transformer) {
+                    contents = transformer(contents);
+                } else {
+                    contents = contents.replace(from, to);
+                }
                 contents += footer ?? '';
                 fs.writeFileSync(item.path, contents, 'utf-8');
                 console.log(`${GREEN_OUT}type fixed ${BOLD_OUT}${item.path}${REGULAR_OUT}`);