fix: docuemntation build breaks

Author: abose

build/api-docs-generator.js

@@ -205,8 +205,34 @@ async function generateMarkdown(file, relativePath) {
 
     const modifiedContent = modifyJs(content, fileName);
 
-    // Generate markdown using jsdoc-to-markdown as a library
-    const markdownContent = await jsdoc2md.render({ source: modifiedContent });
+    // Generate markdown using jsdoc-to-markdown as a library. jsdoc-api spawns
+    // a child `jsdoc` process per call; under our BATCH_SIZE parallelism the
+    // child occasionally produces truncated/empty stdout (manifesting as
+    // "Unexpected end of JSON input"/"Unterminated string in JSON"). Retry
+    // serially so a single transient failure doesn't abort the whole batch.
+    let markdownContent;
+    let lastErr;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            markdownContent = await jsdoc2md.render({ source: modifiedContent });
+            lastErr = undefined;
+            break;
+        } catch (err) {
+            lastErr = err;
+            const causeMsg = err && err.cause && err.cause.message
+                ? err.cause.message
+                : '';
+            const transient = /Unexpected end of JSON input|Unterminated string in JSON|Jsdoc failed/.test(
+                (err && err.message) || ''
+            ) || /JSON/.test(causeMsg);
+            if (!transient) break;
+            await new Promise(r => setTimeout(r, 200 * (attempt + 1)));
+        }
+    }
+    if (lastErr) {
+        lastErr.message = `[${file}] ${lastErr.message}`;
+        throw lastErr;
+    }
     const newContent = normalizeLineEndings(
         modifyMarkdown(markdownContent, path.join(relativePath, fileName))
     );

docs/API-Reference/view/WorkspaceManager.md

@@ -111,7 +111,7 @@ The panel's size & visibility are automatically saved & restored as a view-state
 | $panel | <code>jQueryObject</code> | DOM content to use as the panel. Need not be in the document yet. Must have an id      attribute, for use as a preferences key. |
 | [minSize] | <code>number</code> | @deprecated No longer used. Pass `undefined`. |
 | [title] | <code>string</code> | Display title shown in the bottom panel tab bar. |
-| [options] | <code>Object</code> | Optional settings:   - {string} iconSvg   Path to an SVG icon for the panel tab (e.g. "styles/images/icon.svg").     If omitted, a generic default icon is used. |
+| [options] | <code>Object</code> | Optional settings:   - `iconSvg` (string): Path to an SVG icon for the panel tab (e.g. "styles/images/icon.svg").     If omitted, a generic default icon is used. |
 
 <a name="module_view/WorkspaceManager..destroyBottomPanel"></a>
 

src/view/WorkspaceManager.js

@@ -295,7 +295,7 @@ define(function (require, exports, module) {
      * @param {number=} minSize  @deprecated No longer used. Pass `undefined`.
      * @param {string=} title  Display title shown in the bottom panel tab bar.
      * @param {Object=} options  Optional settings:
-     *   - {string} iconSvg   Path to an SVG icon for the panel tab (e.g. "styles/images/icon.svg").
+     *   - `iconSvg` (string): Path to an SVG icon for the panel tab (e.g. "styles/images/icon.svg").
      *     If omitted, a generic default icon is used.
      * @return {!Panel}
      */