feat: Integrate JSDoc output into vitepress #1240

d3xter666 · 2025-12-11T07:33:20Z

JIRA: CPOUI5FOUNDATION-904

…kdown

…nto jsdoc-to-markdow

cla-assistant · 2025-12-11T07:33:37Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
0 out of 2 committers have signed the CLA.

❌ Gianluca Beil
❌ werwolf2303

Gianluca Beil seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

coveralls · 2025-12-11T07:37:07Z

coverage: 94.691%. remained the same
when pulling f12c503 on jsdoc-to-markdow
into 7e496de on main.

internal/documentation/jsdoc-to-markdown.js

internal/documentation/jsdoc-to-markdown-v1.js

+}
+
+function stripHtmlComments(str) {
+  return str.replace(/<!--[\s\S]*?-->/g, "");


To fully eliminate all HTML comments—taking into account the incomplete removal bug—the stripHtmlComments function needs to apply the replacement repeatedly until no more matches are found. This can be accomplished by wrapping the existing .replace() call in a loop, comparing the previous value to the newly replaced value, and continuing until the string stabilizes. This ensures any newly formed or revealed matches are also sanitized. This change is localized to the stripHtmlComments function—for clarity and safety, no other code needs to be changed. No external dependencies are required for this fix, and the function interface remains the same.

internal/documentation/jsdoc/docdash/publish.js

# Conflicts: # internal/documentation/scripts/downloadPackages.sh

internal/documentation/jsdoc/docdash/publish.js

+
+    // Recursively handle the inner type
+    if (isComplexTypeExpression(innerType)) {
+        result += linkComplexType(innerType, null, classString.replace(' class="', '').replace('"', ''));


In general, to fix this kind of problem you should either use a proper sanitization/escaping library or, if you’re just doing simple character stripping, use a regular expression with the global (g) flag so that all occurrences are replaced, not just the first. When removing quotation marks or similar characters, make sure to handle all instances so partially-sanitized strings cannot cause malformed output.

In this concrete case, the intent on line 748 is to turn something like classString (probably class="SomeClass") into just the inner value (SomeClass) for use as a class attribute when generating links for complex types. The current code does this by first removing the substring class=" and then removing only the first remaining " character. To make this robust, we should (a) remove the leading class=" as now, and then (b) remove all remaining double quotes using a regex with the global flag. This preserves existing behavior for simple cases, but correctly handles any classString with more than one double quote.

Concretely, in internal/documentation/jsdoc/docdash/publish.js, within linkGenericType, change line 748 so that the second .replace uses a global regex: .replace(/"/g, '') instead of .replace('"', ''). No new imports or helper methods are required.

matz3 · 2025-12-19T10:17:58Z

internal/documentation/jsdoc/jsdoc.json

 			}
-		}
+		},
+		"githubSourceBaseUrl": "https://github.com/UI5/cli/blob/main/pacakges/"


Suggested change

"githubSourceBaseUrl": "https://github.com/UI5/cli/blob/main/pacakges/"

"githubSourceBaseUrl": "https://github.com/UI5/cli/blob/main/packages/"

matz3 · 2025-12-19T10:20:06Z

packages/server/lib/middleware/testRunner/TestRunner.js

@@ -1,4 +1,4 @@
-(function(window) {
+nbpm(function(window) {


matz3 · 2025-12-19T10:20:20Z

CONTRIBUTING.md

d3xter666

And one general comment:

We shall not modify the content within packages/ folder, nor delete anything from there. That will impact the UI5 CLI functionality, tests and docs

d3xter666 · 2025-12-19T10:34:01Z

internal/documentation/jsdoc-to-markdown-v1.js

+if (process.argv[2] == "gh-pages") {
+    // Read package.json of packages/builder
+    const builderJson = JSON.parse(fs.readFileSync("tmp/packages/@ui5/builder/package.json"));
+    packageTagName = `https://github.com/UI5/cli/blob/cli-v${builderJson["version"]}/packages/`;


This link is invalid, because the previous versions of UI5 CLI are not within a monorepo, but separate packages and they have separate repositories. There is no packages folder, except for the main branch

d3xter666 · 2025-12-19T10:36:43Z

internal/documentation/jsdoc-to-markdown-v1.js

+	for (const file of fs.readdirSync(outputDirectory)) {
+		fs.rmSync(path.join(outputDirectory, file));
+	}
+}


You can use the rimraf package and clean the whole dir

d3xter666 · 2025-12-19T10:39:03Z

internal/documentation/jsdoc-to-markdown-v1.js

+}
+
+async function checkDeadlinks(link, sourcePath) {
+    if ((await fetch(link)).status != 200) {


It should not be within the 4xx range. Please take a look here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status

d3xter666 · 2025-12-19T10:42:02Z

internal/documentation/jsdoc/docdash/CHANGELOG.md

@@ -0,0 +1,92 @@
+## Modified by SAP


Why is this package copied here, but not used as dependency to the documentation?

d3xter666 · 2025-12-19T10:44:18Z

packages/builder/lib/lbt/resources/ModuleInfo.js

-		 * <pre>
-		 *	 this["name"] = name;
-		 * </pre>


This is how our current JSDoc works. Can we handle this in the transofrmation?
I know that if we leave it like that here, the vitepress build might fail

d3xter666 and others added 19 commits November 27, 2025 14:44

refactor: Improve JSDoc template, so it can easily produce better Mar…

61560c5

…kdown

feat: Initial script for convertion

a0fbad7

Add js script

24cbe75

Fixes

6bd5718

refactor: Improve JSDoc template, so it can easily produce better Mar…

3c2eacc

…kdown

feat: Initial script for convertion

a08dc50

Add js script

48e487c

Fixes

1c7a29e

Modify config.ts for vitepress

450ecb9

Parsing fixes

30754c3

Merge remote-tracking branch 'refs/remotes/origin/jsdoc-to-markdow' i…

1356e1d

…nto jsdoc-to-markdow

Fix last commit

64243bd

Remove file

c3ff120

Update package-lock.json

2d638e4

build: Add jsdoc-to-markdown npm script

037e9e0

build: Rebuild lockfile / Use 'next' tag for package download

a1fa015

Features

64b26ac

Fix internal linking v1

de43c8f

Layout and functionality improvements

85793f8

d3xter666 marked this pull request as draft December 11, 2025 07:33

Gianluca Beil added 2 commits December 11, 2025 14:13

Vitepress build fix and search improvements

7fdadd1

Update package-lock.json

61178f4

github-advanced-security bot found potential problems Dec 11, 2025

View reviewed changes

internal/documentation/jsdoc-to-markdown.js Fixed Show fixed Hide fixed

Gianluca Beil added 2 commits December 15, 2025 14:19

Move to different approach

ee8583f

Move to different approach

9f568b6

github-advanced-security bot found potential problems Dec 15, 2025

View reviewed changes

Gianluca Beil and others added 2 commits December 15, 2025 14:30

Escape HTML tag in TaskUtil.js jsdoc comment

a45980c

Escape HTML tags and replace pre in jsdoc examples

5e507a0

Fixes and move jsdoc to cli

8d9282a

github-advanced-security bot found potential problems Dec 18, 2025

View reviewed changes

internal/documentation/jsdoc/docdash/publish.js Fixed Show fixed Hide fixed

werwolf2303 added 2 commits December 18, 2025 14:53

Merge branch 'escape-html-in-comments' into jsdoc-to-markdow

908e1bb

# Conflicts: # internal/documentation/scripts/downloadPackages.sh

Add back apidocs.css and linking fixes

f12c503

github-advanced-security bot found potential problems Dec 18, 2025

View reviewed changes

werwolf2303 added 2 commits December 19, 2025 09:17

Fix internal linking

8d6101d

Fix external links

c0708db

matz3 reviewed Dec 19, 2025

View reviewed changes

d3xter666 commented Dec 19, 2025

View reviewed changes

@@ -187,7 +187,12 @@
             }
             function stripHtmlComments(str) {
-              return str.replace(/<!--[\s\S]*?-->/g, "");
+              let previous;
+              do {
+                previous = str;
+                str = str.replace(/<!--[\s\S]*?-->/g, "");
+              } while (str !== previous);
+              return str;
             }
             console.log("Conversion done");

@@ -745,7 +745,7 @@
                 // Recursively handle the inner type
                 if (isComplexTypeExpression(innerType)) {
-                    result += linkComplexType(innerType, null, classString.replace(' class="', '').replace('"', ''));
+                    result += linkComplexType(innerType, null, classString.replace(' class="', '').replace(/"/g, ''));
                 } else {
                     let innerUrl = helper.longnameToUrl[innerType];
                     if (innerUrl) {

	"githubSourceBaseUrl": "https://github.com/UI5/cli/blob/main/pacakges/"
	"githubSourceBaseUrl": "https://github.com/UI5/cli/blob/main/packages/"

		@@ -1,4 +1,4 @@
		(function(window) {
		nbpm(function(window) {

feat: Integrate JSDoc output into vitepress #1240

Are you sure you want to change the base?

feat: Integrate JSDoc output into vitepress #1240

Uh oh!

Conversation

d3xter666 commented Dec 11, 2025

Uh oh!

cla-assistant bot commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Check failure

Uh oh!

Copilot Autofix

Uh oh!

Check failure

Copilot Autofix

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d3xter666 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

cla-assistant bot commented Dec 11, 2025 •

edited

Loading

coveralls commented Dec 11, 2025 •

edited

Loading