Skip to content

refactor: JSDoc- align files with openui5 #1673

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
d3xter666 merged 9 commits into from
Oct 21, 2026
Merged

refactor: JSDoc- align files with openui5 #1673

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
fb56484
refactor: JSDoc: ensure that validation can detect use of @experimental
d3xter666 Oct 21, 2026
d58ce61
refactor: JSDoc: support multiline default values in @param tags
d3xter666 Oct 21, 2026
e68fa86
refactor: JSDoc: allow to mark event parameters as optional
d3xter666 Oct 21, 2026
c927cdb
refactor: JSDoc: generated docs should honor module overrides
d3xter666 Oct 21, 2026
9ac6d64
refactor: JSDoc: Enrich param/property with since, experimental, depr…
d3xter666 Oct 21, 2026
698f3e2
refactor: DemoKit: Remove duplicate @since information for properties…
d3xter666 Oct 21, 2026
0d98f9c
refactor: JSDoc: support enum values whose name is not an identifier
d3xter666 Oct 21, 2026
d3a739b
refactor: JSDoc: reduce log messages
d3xter666 Oct 21, 2026
664e906
refactor: JSDoc: Improve empty JSON handling
d3xter666 Oct 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion packages/builder/lib/processors/jsdoc/lib/createIndexFiles.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,11 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
// Handle empty files scenario
resolve({});
} else {
resolve(JSON.parse(String(data)));
try {
resolve(JSON.parse(String(data)));
} catch (oParseError) {
reject(new SyntaxError(`Failed to parse "${file}" as JSON: ${oParseError.message}`));
}
}
});
});
Expand Down
153 changes: 124 additions & 29 deletions packages/builder/lib/processors/jsdoc/lib/transformApiJson.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
const cheerio = require("cheerio");
const path = require('path');
const {TypeParser} = require("./ui5/template/utils/typeParser");
const {extractSince} = require("./ui5/template/utils/versionUtil");
const log = (function() {
try {
return require("@ui5/logger").getLogger("builder:processors:jsdoc:transformApiJson");
Expand Down Expand Up @@ -455,8 +456,20 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
oParameter.defaultValue = formatters.formatDefaultValue(oParameter.defaultValue);

// Description
if (oParameter.description) {
oParameter.description = formatters.formatDescription(oParameter.description);
oParameter.description = formatters.formatDescriptionSince(oParameter.description, oParameter.since);
oParameter.description = formatters.formatDescription(oParameter.description);

// Experimental
if (oParameter.experimental) {
oParameter.experimentalText = formatters.formatExperimental(oParameter.experimental.since ?? oParameter.experimental);
}

// Deprecated
if (oParameter.deprecated) {
const dep = typeof oParameter.deprecated === "string"
? extractSince(oParameter.deprecated)
: { since: oParameter.deprecated.since, value: oParameter.deprecated.text };
oParameter.deprecatedText = formatters.formatDeprecated(dep?.since, dep?.value);
}

});
Expand Down Expand Up @@ -506,11 +519,22 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
oProperty.name = formatters.formatEntityName(oProperty.name, oSymbol.name, oProperty.static);

// Description
// Note: The "@since" information is not appended to the description here because it is
// rendered separately as a dedicated "Since" status in the SubApiDetail view. Appending it
// would duplicate the version information for typedef/enum properties.
oProperty.description = formatters.formatDescription(oProperty.description);

// Experimental
if (oProperty.experimental) {
oProperty.experimentalText = formatters.formatExperimental(oProperty.experimental.since ?? oProperty.experimental);
}

// Deprecated
if (oProperty.deprecated) {
oProperty.description = formatters.formatDescription(oProperty.description,
oProperty.deprecated.text, oProperty.deprecated.since);
} else {
oProperty.description = formatters.formatDescription(oProperty.description);
const dep = typeof oProperty.deprecated === "string"
? extractSince(oProperty.deprecated)
: { since: oProperty.deprecated.since, value: oProperty.deprecated.text };
oProperty.deprecatedText = formatters.formatDeprecated(dep?.since, dep?.value);
}

// Examples
Expand Down Expand Up @@ -582,6 +606,11 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
// Default value
oProperty.defaultValue = formatters.formatDefaultValue(oProperty.defaultValue);

// Experimental
if (oProperty.experimental) {
oProperty.experimentalText = formatters.formatExperimental(oProperty.experimental.since ?? oProperty.experimental);
}

// Deprecated
if (oProperty.deprecated) {
oProperty.deprecatedText = formatters.formatDeprecated(oProperty.deprecated.since,
Expand Down Expand Up @@ -622,6 +651,11 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
oAggregation.description = formatters.formatDescriptionSince(oAggregation.description, oAggregation.since);
}

// Experimental
if (oAggregation.experimental) {
oAggregation.experimentalText = formatters.formatExperimental(oAggregation.experimental.since ?? oAggregation.experimental);
}

// Link enabled
oAggregation.linkEnabled = !isBuiltInType(oAggregation.type);
});
Expand Down Expand Up @@ -649,11 +683,18 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
}

// Description
oAssociation.description = formatters.formatDescriptionSince(oAssociation.description, oAssociation.since);
oAssociation.description = formatters.formatDescription(oAssociation.description);

// Experimental
if (oAssociation.experimental) {
oAssociation.experimentalText = formatters.formatExperimental(oAssociation.experimental.since ?? oAssociation.experimental);
}

// Deprecated
if (oAssociation.deprecated) {
oAssociation.description = formatters.formatDescription(oAssociation.description,
oAssociation.deprecated.text, oAssociation.deprecated.since);
} else {
oAssociation.description = formatters.formatDescriptionSince(oAssociation.description, oAssociation.since);
oAssociation.deprecatedText = formatters.formatDeprecated(oAssociation.deprecated.since,
oAssociation.deprecated.text);
}
});
}
Expand Down Expand Up @@ -784,10 +825,17 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
oParameter.description = formatters.formatDescription(oParameter.description);
}

// Experimental
if (oParameter.experimental) {
oParameter.experimentalText = formatters.formatExperimental(oParameter.experimental.since ?? oParameter.experimental);
}

// Deprecated
if (oParameter.deprecated) {
oParameter.deprecatedText = formatters.formatDeprecated(oParameter.deprecated.since,
oParameter.deprecated.text);
const dep = typeof oParameter.deprecated === "string"
? extractSince(oParameter.deprecated)
: { since: oParameter.deprecated.since, value: oParameter.deprecated.text };
oParameter.deprecatedText = formatters.formatDeprecated(dep?.since, dep?.value);
}
});
}
Expand Down Expand Up @@ -827,7 +875,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,

// Deprecated
if (oMethod.deprecated) {
oMethod.deprecatedText = formatters.formatEventDeprecated(oMethod.deprecated.since,
oMethod.deprecatedText = formatters.formatMethodDeprecated(oMethod.deprecated.since,
oMethod.deprecated.text);
}

Expand All @@ -842,11 +890,20 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
oParameter.defaultValue = formatters.formatDefaultValue(oParameter.defaultValue);

// Description
oParameter.description = formatters.formatDescriptionSince(oParameter.description, oParameter.since);
oParameter.description = formatters.formatDescription(oParameter.description);

// Experimental
if (oParameter.experimental) {
oParameter.experimentalText = formatters.formatExperimental(oParameter.experimental.since ?? oParameter.experimental);
}

// Deprecated
if (oParameter.deprecated) {
oParameter.description = formatters.formatDescription(oParameter.description,
oParameter.deprecated.text, oParameter.deprecated.since);
} else {
oParameter.description = formatters.formatDescription(oParameter.description);
const dep = typeof oParameter.deprecated === "string"
? extractSince(oParameter.deprecated)
: { since: oParameter.deprecated.since, value: oParameter.deprecated.text };
oParameter.deprecatedText = formatters.formatDeprecated(dep?.since, dep?.value);
}

});
Expand Down Expand Up @@ -976,21 +1033,29 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
oChainObject.aDependentLibraryFiles.forEach((sFile) => {
aPromises.push(new Promise((oResolve) => {
fs.readFile(sFile, 'utf8', (oError, oData) => {
oResolve(oError ? false : oData);
oResolve(oError ? false : {sFile, sData: oData});
});
}));
});
return Promise.all(aPromises).then((aValues) => {
const oDependentAPIs = {};

aValues.forEach((sData) => {
aValues.forEach((oValue) => {
if (!oValue) {
return;
}
const {sFile, sData} = oValue;
let oData;

try {
oData = JSON.parse(sData);
} catch (e) {
// Silence possible dependency library invalid json errors as they are not critical
// and we should not fail BCP: 1870560058
// Dependency library files are not critical; log and continue instead of failing. BCP: 1870560058
if (sData.trim() === "") {
log.verbose(`The file "${sFile}" is empty.`);
} else {
log.verbose(`Failed to parse "${sFile}" as JSON: ${e.message}`);
}
}

// OpenUI5 build specific - own library can be listed as dependency library also.
Expand Down Expand Up @@ -1248,12 +1313,16 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,

fs.readFile(sPath, 'utf8', (oError, oFileData) => {
if (!oError) {
oFileData = JSON.parse(oFileData);
if (oFileData.explored && oFileData.explored.entities && oFileData.explored.entities.length > 0) {
oChainObject.entitiesWithSamples = [];
oFileData.explored.entities.forEach((oEntity) => {
oChainObject.entitiesWithSamples.push(oEntity.id);
});
try {
oFileData = JSON.parse(oFileData);
if (oFileData.explored && oFileData.explored.entities && oFileData.explored.entities.length > 0) {
oChainObject.entitiesWithSamples = [];
oFileData.explored.entities.forEach((oEntity) => {
oChainObject.entitiesWithSamples.push(oEntity.id);
});
}
} catch (oParseError) {
log.error(`Failed to parse file "${sPath}": ${oParseError.message}`);
}
}
// We always resolve as this data is not mandatory
Expand All @@ -1273,9 +1342,17 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
fs.readFile(sInputFile, 'utf8', (oError, sFileData) => {
if (oError) {
oReject(oError);
} else {
return;
}
try {
oChainObject.fileData = JSON.parse(sFileData);
oResolve(oChainObject);
} catch (oParseError) {
if (sFileData.trim() === "") {
oReject(new SyntaxError(`The file "${sInputFile}" is empty.`));
} else {
oReject(new SyntaxError(`Failed to parse "${sInputFile}" as JSON: ${oParseError.message}`));
}
}
});
});
Expand Down Expand Up @@ -1490,6 +1567,10 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
return result;
},

formatExperimental: function (sExperimentalSince) {
return `Experimental since ${sExperimentalSince}`;
},

/**
* Formats the default value of the property as a string.
* @param defaultValue - the default value of the property
Expand Down Expand Up @@ -2414,9 +2495,23 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
// Phone name - available only for parameters
oProperty.phoneName = [aPhoneName.join("."), oProperty.name].join(".");

// Description (no deprecation etc. possible in JSDoc)
// Description
// Note: The "@since" information is not appended to the description here because it is
// rendered separately as a dedicated "Since" status in the SubApiDetail view. Appending it
// would duplicate the version information for typedef/enum properties.
oProperty.description = formatters.formatDescription(oProperty.description);

// Experimental
if (oProperty.experimental) {
oProperty.experimentalText = formatters.formatExperimental(oProperty.experimental.since ?? oProperty.experimental);
}

// Deprecated
if (oProperty.deprecated) {
oProperty.deprecatedText = formatters.formatDeprecated(oProperty.deprecated.since,
oProperty.deprecated.text);
}

// Add property to parameter array as we need a simple structure
aProperties.push(oProperty);

Expand Down
Loading
Loading