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.

Author: marklundin

utils/plugins/rollup-types-fixup.mjs

@@ -191,12 +191,29 @@ 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} */` : '';
+                    // console.log(prop[0], contents.match(`@property {${prop[1]}} ${prop[0]}`), 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 +260,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}`);