Skip to content
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

Align jsdoc template with openui5 #1100

Merged
merged 12 commits into from
Dec 10, 2024
Merged

Align jsdoc template with openui5 #1100

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
c526c12
[INTERNAL] lib/processors/jsdoc: Fix missing quote in ui5/plugin.js
codeworrior Dec 5, 2024
a7d0c7a
[INTERNAL] lib/processors/jsdoc: Remove debug console log
codeworrior Dec 5, 2024
73d7fd1
[INTERNAL] lib/processors/jsdoc: Simplify base type handling
codeworrior Dec 5, 2024
d6782c7
[INTERNAL] lib/processors/jsdoc: Simplify base type handling (fixup)
codeworrior Dec 5, 2024
44a7b47
[INTERNAL] lib/processors/jsdoc: Enhance visualization of multiple types
codeworrior Dec 5, 2024
dc7d1e6
[INTERNAL] lib/processors/jsdoc: remove duplicates after `processingC…
codeworrior Dec 5, 2024
bbd9c6a
[INTERNAL] lib/processors/jsdoc: prefer strict comparison over type c…
codeworrior Dec 5, 2024
84a8d97
[INTERNAL] lib/processors/jsdoc: Fix inconsistencies as reported by o…
codeworrior Dec 5, 2024
c0cf606
[INTERNAL] lib/processors/jsdoc: Enable sap/base enums to be used as …
codeworrior Dec 5, 2024
38f8388
[INTERNAL] lib/processors/jsdoc: Entity type visualization improved
codeworrior Dec 5, 2024
e5d151c
[INTERNAL] lib/processors/jsdoc: fix JSDoc issues in the code of the …
codeworrior Dec 5, 2024
0e3d0b8
[INTERNAL] lib/processors/jsdoc: fix eslint errors
codeworrior Dec 10, 2024
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
119 changes: 58 additions & 61 deletions lib/processors/jsdoc/lib/createIndexFiles.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,12 +39,12 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
log.info("Using custom fs");
}
if (returnOutputFiles) {
log.info("Returning output files instead of writing to fs.")
log.info("Returning output files instead of writing to fs.");
}
log.info("");

// Deprecated, Experimental and Since collections
let oListCollection = {
const oListCollection = {
deprecated: {
noVersion: {
apis: []
Expand All @@ -63,13 +63,11 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
fs.readFile(file, 'utf8', function (err, data) {
if (err) {
reject(err);
} else {
} else if (data.trim() === "") {
// Handle empty files scenario
if (data.trim() === "") {
resolve({});
} else {
resolve(JSON.parse(String(data)));
}
resolve({});
} else {
resolve(JSON.parse(String(data)));
}
});
});
Expand Down Expand Up @@ -102,20 +100,20 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
* Returns a promise that resolves with an array of symbols.
*/
function createSymbolSummaryForLib(lib) {
let file = path.join(unpackedTestresourcesRoot, lib.replace(/\./g, "/"), "designtime/api.json");
const file = path.join(unpackedTestresourcesRoot, lib.replace(/\./g, "/"), "designtime/api.json");

return readJSONFile(file).then(function (apijson) {
if (!apijson.hasOwnProperty("symbols") || !Array.isArray(apijson.symbols)) {
// Ignore libraries with invalid api.json content like empty object or non-array "symbols" property.
return [];
}
return apijson.symbols.map(symbol => {
let oReturn = {
return apijson.symbols.map((symbol) => {
const oReturn = {
name: symbol.name,
kind: symbol.kind,
visibility: symbol.visibility,
extends: symbol.extends,
implements: symbol.implements,
"extends": symbol.extends,
"implements": symbol.implements,
lib: lib
};
// We add deprecated member only when the control is deprecated to keep file size at check
Expand All @@ -132,7 +130,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
collectLists(symbol);
return oReturn;
});
})
});
}

/*
Expand All @@ -146,7 +144,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
const sText = oDataType !== "since" ? oEntityObject[oDataType].text : oEntityObject.description;
const oData = {
control: sSymbolName,
text: sText || undefined,
text: sText || undefined,
type: sObjectType,
"static": !!oEntityObject.static,
visibility: oEntityObject.visibility
Expand All @@ -159,7 +157,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile

if (sSince && sSince !== "undefined" /* Sometimes sSince comes as string "undefined" */) {
// take only major and minor versions
let sVersion = sSince.split(".").slice(0, 2).join(".");
const sVersion = sSince.split(".").slice(0, 2).join(".");

oData.since = sSince;

Expand Down Expand Up @@ -190,7 +188,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
}

// Methods
oSymbol.methods && oSymbol.methods.forEach(oMethod => {
oSymbol.methods?.forEach((oMethod) => {
if (oMethod.deprecated) {
addData("deprecated", oMethod, "methods", oSymbol.name);
}
Expand All @@ -205,7 +203,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
});

// Events
oSymbol.events && oSymbol.events.forEach(oEvent => {
oSymbol.events?.forEach((oEvent) => {
if (oEvent.deprecated) {
addData("deprecated", oEvent, "events", oSymbol.name);
}
Expand All @@ -229,24 +227,24 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
}

function expandHierarchyInfo(symbols) {
let byName = new Map();
symbols.forEach(symbol => {
const byName = new Map();
symbols.forEach((symbol) => {
byName.set(symbol.name, symbol);
});
symbols.forEach(symbol => {
let parent = symbol.extends && byName.get(symbol.extends);
symbols.forEach((symbol) => {
const parent = symbol.extends && byName.get(symbol.extends);
if (parent) {
parent.extendedBy = parent.extendedBy ||  [];
parent.extendedBy = parent.extendedBy || [];
parent.extendedBy.push({
name: symbol.name,
visibility: symbol.visibility
});
}
if (symbol.implements) {
symbol.implements.forEach(intfName => {
let intf = byName.get(intfName);
symbol.implements.forEach((intfName) => {
const intf = byName.get(intfName);
if (intf) {
intf.implementedBy = intf.implementedBy ||  [];
intf.implementedBy = intf.implementedBy || [];
intf.implementedBy.push({
name: symbol.name,
visibility: symbol.visibility
Expand All @@ -259,23 +257,23 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
}

function convertListToTree(symbols) {
let aTree = [];
const aTree = [];

// Filter out excluded libraries
symbols = symbols.filter(({lib}) => ["sap.ui.documentation"].indexOf(lib) === -1);

// Create treeName and displayName
symbols.forEach(oSymbol => {
symbols.forEach((oSymbol) => {
oSymbol.treeName = oSymbol.name.replace(/^module:/, "").replace(/\//g, ".");
oSymbol.displayName = oSymbol.treeName.split(".").pop();
});

// Create missing - virtual namespaces
symbols.forEach(oSymbol => {
symbols.forEach((oSymbol) => {
oSymbol.treeName.split(".").forEach((sPart, i, a) => {
let sName = a.slice(0, (i + 1)).join(".");
const sName = a.slice(0, (i + 1)).join(".");

if (!symbols.find(o => o.treeName === sName)) {
if (!symbols.find((o) => o.treeName === sName)) {
symbols.push({
name: sName,
treeName: sName,
Expand All @@ -289,13 +287,12 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
});

// Discover parents
symbols.forEach(oSymbol => {
let aParent = oSymbol.treeName.split("."),
sParent;
symbols.forEach((oSymbol) => {
const aParent = oSymbol.treeName.split(".");

// Extract parent name
aParent.pop();
sParent = aParent.join(".");
const sParent = aParent.join(".");

// Mark parent
if (symbols.find(({treeName}) => treeName === sParent)) {
Expand All @@ -305,20 +302,20 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile

// Sort the list before building the tree
symbols.sort((a, b) => {
let sA = a.treeName.toUpperCase(),
const sA = a.treeName.toUpperCase(),
sB = b.treeName.toUpperCase();

if (sA < sB) return -1;
if (sA > sB) return 1;
if (sA < sB) {return -1;}
if (sA > sB) {return 1;}
return 0;
});

// Build tree
symbols.forEach(oSymbol => {
symbols.forEach((oSymbol) => {
if (oSymbol.parent) {
let oParent = symbols.find(({treeName}) => treeName === oSymbol.parent);
const oParent = symbols.find(({treeName}) => treeName === oSymbol.parent);

if (!oParent.nodes) oParent.nodes = [];
if (!oParent.nodes) {oParent.nodes = [];}
oParent.nodes.push(oSymbol);
} else {
aTree.push(oSymbol);
Expand All @@ -327,13 +324,13 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile

// Custom sort first level tree items - "sap" namespace should be on top
aTree.sort((a, b) => {
let sA = a.displayName.toUpperCase(),
const sA = a.displayName.toUpperCase(),
sB = b.displayName.toUpperCase();

if (sA === "SAP") return -1;
if (sB === "SAP") return 1;
if (sA < sB) return -1;
if (sA > sB) return 1;
if (sA === "SAP") {return -1;}
if (sB === "SAP") {return 1;}
if (sA < sB) {return -1;}
if (sA > sB) {return 1;}

return 0;
});
Expand All @@ -349,10 +346,10 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
delete oSymbol.treeName;
delete oSymbol.parent;
if (oSymbol.nodes) {
oSymbol.nodes.forEach(o => cleanTree(o));
oSymbol.nodes.forEach((o) => cleanTree(o));
}
}
aTree.forEach(o => cleanTree(o));
aTree.forEach((o) => cleanTree(o));

return aTree;
}
Expand Down Expand Up @@ -401,7 +398,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
propagateFlags(oSymbol, { bAllContentDeprecated: true });
} else {
// 3. If all children are deprecated, then the parent is marked as content-deprecated
oSymbol.bAllContentDeprecated = !!oSymbol.nodes && oSymbol.nodes.every(node => node.bAllContentDeprecated);
oSymbol.bAllContentDeprecated = !!oSymbol.nodes && oSymbol.nodes.every((node) => node.bAllContentDeprecated);
}
}

Expand All @@ -413,9 +410,9 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
function propagateFlags(oSymbol, oFlags) {
Object.assign(oSymbol, oFlags);
if (oSymbol.nodes) {
oSymbol.nodes.forEach(node => {
oSymbol.nodes.forEach((node) => {
propagateFlags(node, oFlags);
})
});
}
}

Expand All @@ -424,11 +421,11 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
const filesToReturn = {};

var p = readJSONFile(versionInfoFile)
.then(versionInfo => {
.then((versionInfo) => {
version = versionInfo.version;
return Promise.all(
versionInfo.libraries.map(
lib => createSymbolSummaryForLib(lib.name).catch(err => {
(lib) => createSymbolSummaryForLib(lib.name).catch((err) => {
// ignore 'file not found' errors as some libs don't have an api.json (themes, server libs)
if (err.code === 'ENOENT') {
return [];
Expand All @@ -441,8 +438,8 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
.then(deepMerge)
.then(expandHierarchyInfo)
.then(convertListToTree)
.then(symbols => {
let result = {
.then((symbols) => {
const result = {
"$schema-ref": "http://schemas.sap.com/sapui5/designtime/api-index.json/1.0",
version: version,
library: "*",
Expand All @@ -456,13 +453,13 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
})
.then(() => {
/* Lists - modify and cleanup */
let sortList = function (oList) {
const sortList = function (oList) {
/* Sorting since records */
let aKeys = Object.keys(oList),
const aKeys = Object.keys(oList),
oSorted = {};

aKeys.sort((a, b) => {
let aA = a.split("."),
const aA = a.split("."),
aB = b.split(".");

if (a === "noVersion") {
Expand All @@ -478,7 +475,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
b = [aB[0], ('0' + aB[1]).slice(-2)].join("");

// Sort descending
return parseInt(b, 10) - parseInt(a, 10);
return parseInt(b) - parseInt(a);
});

aKeys.forEach((sKey) => {
Expand Down Expand Up @@ -529,8 +526,8 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
]);
}
})
.catch(err => {
log.error("**** failed to create API index for libraries:", err)
.catch((err) => {
log.error("**** failed to create API index for libraries:", err);
throw err;
});

Expand Down
Loading
Loading