Address all new feedback: add types, make TSDoc a link, use dynamic element, add warning for unprocessed elements

Co-authored-by: mbohal <4589176+mbohal@users.noreply.github.com>

Author: Copilot

package.json

@@ -70,7 +70,7 @@
     "webpack-dev-server": "^5.2.0"
   },
   "scripts": {
-    "build": "webpack --mode=production && node scripts/processDocoffFunctionDoc.js",
+    "build": "webpack --mode=production",
     "prepublishOnly": "npm run build",
     "start": "webpack serve --mode=development",
     "test": "npm run test:eslint && npm run test:jest",

public/index.html

@@ -239,7 +239,7 @@ <h3>Layout</h3>
 
       <h2><code>docoff-function-doc</code></h2>
 
-      <p><code>&ltdocoff-function-doc&gt;</code> displays function documentation extracted from TSDoc comments in TypeScript files.</p>
+      <p><code>&ltdocoff-function-doc&gt;</code> displays function documentation extracted from <a href="https://tsdoc.org/" target="_blank">TSDoc</a> comments in TypeScript files.</p>
 
       <h3>Usage</h3>
 
@@ -252,7 +252,7 @@ <h3>Example</h3>
 
       <p>Displaying documentation for example functions:</p>
 
-      <dl><dt><strong>formatName</strong></dt><dd>Formats a user's full name with proper capitalization</dd><dt>Parameter: <code>firstName</code></dt><dd>The user's first name</dd><dt>Parameter: <code>lastName</code></dt><dd>The user's last name</dd><dt>Parameter: <code>includeTitle</code></dt><dd>Whether to include a title prefix</dd><dt>Returns:</dt><dd>The formatted full name</dd></dl>
+      <dl><dt><strong>formatName</strong></dt><dd>Formats a user's full name with proper capitalization</dd><dt>Parameter: <code>firstName</code>: <span style="color: #0066cc;">string</span></dt><dd>The user's first name</dd><dt>Parameter: <code>lastName</code>: <span style="color: #0066cc;">string</span></dt><dd>The user's last name</dd><dt>Parameter: <code>includeTitle</code>: <span style="color: #0066cc;">boolean</span> (optional)</dt><dd>Whether to include a title prefix</dd><dt>Returns: <span style="color: #009900;">string</span></dt><dd>The formatted full name</dd></dl>
 
     </div>
 

scripts/processDocoffFunctionDoc.js

@@ -98,6 +98,9 @@ async function generateFunctionDoc(filePath, functionName, baseDir) {
     throw new Error(`No TSDoc comment found for function '${functionName}'`);
   }
 
+  // Extract type information from the function
+  const typeInfo = extractTypeInformation(functionNode);
+
   // Parse TSDoc comment
   const parser = new TSDocParser();
   const parserContext = parser.parseString(tsdocComment);
@@ -107,7 +110,7 @@ async function generateFunctionDoc(filePath, functionName, baseDir) {
   }
 
   // Generate HTML from parsed TSDoc
-  return generateHTMLFromTSDoc(functionName, parserContext.docComment);
+  return generateHTMLFromTSDoc(functionName, parserContext.docComment, typeInfo);
 }
 
 function findFunctionNode(sourceFile, functionName) {
@@ -155,7 +158,41 @@ function extractTSDocComment(sourceFile, functionNode) {
   return null;
 }
 
-function generateHTMLFromTSDoc(functionName, docComment) {
+function extractTypeInformation(functionNode) {
+  const typeInfo = {
+    parameters: [],
+    returnType: null
+  };
+
+  // Extract parameter types
+  if (functionNode.parameters) {
+    for (const param of functionNode.parameters) {
+      const paramName = param.name.text;
+      let paramType = 'any';
+      
+      if (param.type) {
+        paramType = param.type.getText();
+      }
+      
+      const isOptional = param.questionToken !== undefined || param.initializer !== undefined;
+      
+      typeInfo.parameters.push({
+        name: paramName,
+        type: paramType,
+        optional: isOptional
+      });
+    }
+  }
+
+  // Extract return type
+  if (functionNode.type) {
+    typeInfo.returnType = functionNode.type.getText();
+  }
+
+  return typeInfo;
+}
+
+function generateHTMLFromTSDoc(functionName, docComment, typeInfo) {
   const summary = docComment.summarySection;
   const params = docComment.params;
   const returnsBlock = docComment.returnsBlock;
@@ -175,15 +212,22 @@ function generateHTMLFromTSDoc(functionName, docComment) {
     for (const param of params.blocks) {
       const paramName = param.parameterName;
       const paramDescription = param.content ? extractTextFromNodes(param.content.nodes) : '';
-      html += `<dt>Parameter: <code>${paramName}</code></dt>`;
+      
+      // Find type information for this parameter
+      const typeInfoParam = typeInfo.parameters.find(p => p.name === paramName);
+      const typeDisplay = typeInfoParam ? `<span style="color: #0066cc;">${typeInfoParam.type}</span>` : '';
+      const optionalDisplay = typeInfoParam && typeInfoParam.optional ? ' (optional)' : '';
+      
+      html += `<dt>Parameter: <code>${paramName}</code>${typeDisplay ? `: ${typeDisplay}` : ''}${optionalDisplay}</dt>`;
       html += `<dd>${paramDescription}</dd>`;
     }
   }
 
   // Returns
   if (returnsBlock && returnsBlock.content) {
     const returnDescription = extractTextFromNodes(returnsBlock.content.nodes);
-    html += `<dt>Returns:</dt>`;
+    const returnTypeDisplay = typeInfo.returnType ? `<span style="color: #009900;">${typeInfo.returnType}</span>` : '';
+    html += `<dt>Returns${returnTypeDisplay ? `: ${returnTypeDisplay}` : ''}</dt>`;
     html += `<dd>${returnDescription}</dd>`;
   }
 

src/DocoffFunctionDoc/DocoffFunctionDoc.js

@@ -0,0 +1,36 @@
+/**
+ * Custom element for displaying function documentation
+ * Shows a warning when not processed by the webpack plugin
+ */
+export class DocoffFunctionDoc extends HTMLElement {
+  static get observedAttributes() {
+    return ['src'];
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback() {
+    this.render();
+  }
+
+  get src() {
+    return this.getAttribute('src');
+  }
+
+  render() {
+    if (!this.src) {
+      this.innerHTML = '<div style="color: red;">Error: src attribute is required</div>';
+      return;
+    }
+
+    // If this element is still present, it means the webpack plugin didn't process it
+    this.innerHTML = `
+      <div style="background: #fff3cd; border: 1px solid #ffeaa7; padding: 10px; border-radius: 4px; color: #856404;">
+        <strong>Warning:</strong> This file needs to be processed through the build system first.
+        <br>Function documentation for <code>${this.src}</code> will be generated during build.
+      </div>
+    `;
+  }
+}

src/DocoffFunctionDoc/index.js

@@ -0,0 +1 @@
+export { DocoffFunctionDoc } from './DocoffFunctionDoc';

src/main.js

@@ -2,11 +2,13 @@ import { DocoffPlaceholder } from './DocoffPlaceholder';
 import { DocoffReactPreview } from './DocoffReactPreview';
 import { DocoffReactBase } from './DocoffReactBase';
 import { DocoffReactProps } from './DocoffReactProps';
+import { DocoffFunctionDoc } from './DocoffFunctionDoc';
 
 customElements.define('docoff-react-preview', DocoffReactPreview, { extends: 'textarea' });
 customElements.define('docoff-react-base', DocoffReactBase, { extends: 'textarea' });
 customElements.define('docoff-react-props', DocoffReactProps);
 customElements.define('docoff-placeholder', DocoffPlaceholder);
+customElements.define('docoff-function-doc', DocoffFunctionDoc);
 
 // For comfortable usage in Markdown any `<code>` elements with class `language-docoff-*`
 // get replaced by the respective custom elements