Skip to content

Commit

Permalink
[FIX] Align JSDoc template and scripts with OpenUI5 1.79 (#460)
Browse files Browse the repository at this point in the history
  • Loading branch information
@codeworrior
codeworrior authored May 19, 2020
1 parent 5732901 commit c868fa0
Show file tree
Hide file tree
Showing 4 changed files with 614 additions and 154 deletions.
76 changes: 71 additions & 5 deletions lib/processors/jsdoc/lib/createIndexFiles.js
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/*
* Node script to create cross-library API index files for use in the UI5 SDKs.
*
* (c) Copyright 2009-2019 SAP SE or an SAP affiliate company.
* (c) Copyright 2009-2020 SAP SE or an SAP affiliate company.
* Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
*/

Expand Down Expand Up @@ -248,13 +248,12 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
let aTree = [];

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

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

// Create missing - virtual namespaces
Expand All @@ -269,8 +268,7 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
displayName: sPart,
lib: oSymbol.lib,
kind: "namespace",
visibility: "public", // Virtual namespace are always public
bIsDeprecated: false // Virtual namespace can't be deprecated
visibility: "public" // Virtual namespace are always public
});
}
});
Expand Down Expand Up @@ -326,6 +324,12 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
return 0;
});

// walk the tree *from bottom to top*
// in order to detect all parent nodes
// that should be marked as content-deprecated
// because their children are explicitly deprecated
toChildrenFirstArray(aTree).forEach(markDeprecatedNodes);

// Clean tree - keep file size down
function cleanTree (oSymbol) {
delete oSymbol.treeName;
Expand All @@ -339,6 +343,68 @@ function createIndexFiles(versionInfoFile, unpackedTestresourcesRoot, targetFile
return aTree;
}

/**
* Creates an array of all tree nodes,
* where the child nodes precede the parent nodes
* @param aTree
* @returns {Array}
*/
function toChildrenFirstArray(aTree) {
var aChildrenFirst = [];
function addToLeafsFirst(node) {
if (node.nodes) {
node.nodes.forEach(function(child) {
addToLeafsFirst(child);
});
}
aChildrenFirst.push(node);
}
aTree.forEach(function(parent) {
addToLeafsFirst(parent);
});
return aChildrenFirst;
}

/**
* Sets the <code>bAllContentDeprecated</code> flag of each symbol
*
* The <code>bAllContentDeprecated</code> flag differs from the already existing <code>deprecated</code> flag
* in the following respect:
*
* 1) if a node is deprecated => all its children should be marked as <code>bAllContentDeprecated</code>
* (even if not explicitly deprecated in their JSDoc)
* 2) if all children of the node are deprecated => that node should also be marked as <code>bAllContentDeprecated</code>
* (even if not explicitly deprecated in its JSDoc)
* 3) if a node is explicitly deprecated in its JSDoc => it should also be marked as <code>bAllContentDeprecated</code>
* (for consistency)
*
* @param oSymbol
*/
function markDeprecatedNodes(oSymbol) {
// 1. If the symbol is deprecated all content in it should be also deprecated
if (oSymbol.deprecated) {
// 2. If all content in the symbol is deprecated, flag should explicitly be passed to its child nodes.
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);
}
}

/**
* Merges the set of flags from <code>oFlags</code> into the given <code>oSymbol</code>
* @param oSymbol
* @param oFlags
*/
function propagateFlags(oSymbol, oFlags) {
Object.assign(oSymbol, oFlags);
if (oSymbol.nodes) {
oSymbol.nodes.forEach(node => {
propagateFlags(node, oFlags);
})
}
}

function createOverallIndex() {
let version = "0.0.0";
const filesToReturn = {};
Expand Down
127 changes: 81 additions & 46 deletions lib/processors/jsdoc/lib/transformApiJson.js
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/*
* Node script to preprocess api.json files for use in the UI5 SDKs.
*
* (c) Copyright 2009-2019 SAP SE or an SAP affiliate company.
* (c) Copyright 2009-2020 SAP SE or an SAP affiliate company.
* Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
*/

Expand Down Expand Up @@ -132,16 +132,24 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
// Attach children info
symbols.forEach(oSymbol => {
if (oSymbol.parent) {
let oParent = symbols.find(({treeName}) => treeName === oSymbol.parent);
let oParent = symbols.find(({treeName}) => treeName === oSymbol.parent),
oNode;

if (!oParent.nodes) oParent.nodes = [];
oParent.nodes.push({

oNode = {
name: oSymbol.displayName,
description: formatters._preProcessLinksInTextBlock(
extractFirstSentence(oSymbol.description)
),
href: "#/api/" + encodeURIComponent(oSymbol.name)
});
href: "api/" + encodeURIComponent(oSymbol.name)
};

if (oSymbol.deprecated) {
oNode.deprecated = true;
}

oParent.nodes.push(oNode);
}
});

Expand Down Expand Up @@ -308,7 +316,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
// Link Enabled
if (oSymbol.kind !== "enum" && !isBuiltInType(oProperty.type) && possibleUI5Symbol(oProperty.type)) {
oProperty.linkEnabled = true;
oProperty.href = "#/api/" + oProperty.type.replace("[]", "");
oProperty.href = "api/" + oProperty.type.replace("[]", "");
}

// Keep file size in check
Expand Down Expand Up @@ -392,7 +400,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
oAggregation.description = formatters.formatDescription(oAggregation.description,
oAggregation.deprecated.text, oAggregation.deprecated.since);
} else {
oAggregation.description = formatters.formatDescription(oAggregation.description);
oAggregation.description = formatters.formatDescriptionSince(oAggregation.description, oAggregation.since);
}

// Link enabled
Expand Down Expand Up @@ -426,13 +434,39 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
oAssociation.description = formatters.formatDescription(oAssociation.description,
oAssociation.deprecated.text, oAssociation.deprecated.since);
} else {
oAssociation.description = formatters.formatDescription(oAssociation.description);
oAssociation.description = formatters.formatDescriptionSince(oAssociation.description, oAssociation.since);
}
});
}

// Events
if (oMeta.events) {

oMeta.events.forEach(oEvent => {
let aParams = oEvent.parameters;

aParams && Object.keys(aParams).forEach(sParam => {
let sSince = aParams[sParam].since;
let oDeprecated = aParams[sParam].deprecated;
let oEvtInSymbol = oSymbol.events.find(e => e.name === oEvent.name);
let oParamInSymbol = oEvtInSymbol && oEvtInSymbol.parameters[0] &&
oEvtInSymbol.parameters[0].parameterProperties &&
oEvtInSymbol.parameters[0].parameterProperties.getParameters &&
oEvtInSymbol.parameters[0].parameterProperties.getParameters.parameterProperties &&
oEvtInSymbol.parameters[0].parameterProperties.getParameters.parameterProperties[sParam];

if (typeof oParamInSymbol === 'object' && oParamInSymbol !== null) {
if (sSince) {
oParamInSymbol.since = sSince;
}

if (oDeprecated) {
oParamInSymbol.deprecated = oDeprecated;
}
}
})
});

// We don't need event's data from the UI5-metadata for now. Keep file size in check
delete oMeta.events;
}
Expand Down Expand Up @@ -508,13 +542,15 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
}

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

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

Expand All @@ -535,8 +571,8 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
oMethod.name = formatters.formatEntityName(oMethod.name, oSymbol.name, oMethod.static);

// Link
oMethod.href = "#/api/" + encodeURIComponent(oSymbol.name) +
"/methods/" + encodeURIComponent(oMethod.name);
oMethod.href = "api/" + oSymbol.name +
"#methods/" + oMethod.name;
}

formatters.formatReferencesInDescription(oMethod);
Expand Down Expand Up @@ -571,7 +607,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
// Link Enabled
if (!isBuiltInType(oType.value) && possibleUI5Symbol(oType.value)) {
oType.linkEnabled = true;
oType.href = "#/api/" + oType.value.replace("[]", "");
oType.href = "api/" + oType.value.replace("[]", "");
}

});
Expand Down Expand Up @@ -603,7 +639,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,

// Link Enabled
if (!isBuiltInType(oType.value)) {
oType.href = "#/api/" + encodeURIComponent(oType.value.replace("[]", ""));
oType.href = "api/" + oType.value.replace("[]", "");
oType.linkEnabled = true;
}

Expand Down Expand Up @@ -993,11 +1029,13 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
* @returns string - the formatted text
*/
formatAnnotationNamespace: function (namespace) {
var result,
aNamespaceParts = namespace.split(".");
var aNamespaceParts = namespace.split("."),
result, target, text;

if (aNamespaceParts[0] === "Org" && aNamespaceParts[1] === "OData") {
result = '<a href="' + this.ANNOTATIONS_NAMESPACE_LINK + namespace + '.xml">' + namespace + '</a>';
target = this.ANNOTATIONS_NAMESPACE_LINK + namespace + ".xml";
text = namespace;
result = this.handleExternalUrl(target, text);
} else {
result = namespace;
}
Expand Down Expand Up @@ -1110,15 +1148,15 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
var sReturn;

switch (defaultValue) {
case null:
case undefined:
sReturn = '';
break;
case '':
sReturn = 'empty string';
break;
default:
sReturn = defaultValue;
case null:
case undefined:
sReturn = '';
break;
case '':
sReturn = 'empty string';
break;
default:
sReturn = defaultValue;
}

return Array.isArray(sReturn) ? sReturn.join(', ') : sReturn;
Expand Down Expand Up @@ -1313,7 +1351,7 @@ title="Information published on ${bSAPHosted ? '' : 'non '}SAP site" class="sapU
let oProperty = findProperty(oSymbol, methodName, target);
if (oProperty) {
sResult = this.createLink({
name: oProperty.name,
name: className,
text: text
});
return true;
Expand Down Expand Up @@ -1409,21 +1447,18 @@ title="Information published on ${bSAPHosted ? '' : 'non '}SAP site" class="sapU
name = name.replace(/^module:/, "");
}

name = encodeURIComponent(name);
className = encodeURIComponent(className);

// Build the link
sLink = type ? `${className}/${type}/${name}` : name;
sLink = type ? `${className}#${type}/${name}` : name;

if (hrefAppend) {
sLink += hrefAppend;
}

if (local) {
return `<a target="_self" class="jsdoclink scrollTo${type === `events` ? `Event` : `Method`}" data-sap-ui-target="${name}" href="#/api/${sLink}">${text}</a>`;
return `<a target="_self" class="jsdoclink scrollTo${type === `events` ? `Event` : `Method`}" data-target="${name}" href="api/${sLink}">${text}</a>`;
}

return `<a target="_self" class="jsdoclink" href="#/api/${sLink}">${text}</a>`;
return `<a target="_self" class="jsdoclink" href="api/${sLink}">${text}</a>`;
},

/**
Expand Down Expand Up @@ -1453,7 +1488,7 @@ title="Information published on ${bSAPHosted ? '' : 'non '}SAP site" class="sapU
// topic:xxx Topic
aMatch = sTarget.match(/^topic:(\w{32})$/);
if (aMatch) {
return '<a target="_self" href="#/topic/' + aMatch[1] + '">' + sText + '</a>';
return '<a target="_self" href="topic/' + aMatch[1] + '">' + sText + '</a>';
}

// sap.x.Xxx.prototype.xxx - In case of prototype we have a link to method
Expand Down Expand Up @@ -1499,7 +1534,7 @@ title="Information published on ${bSAPHosted ? '' : 'non '}SAP site" class="sapU

return this.createLink({
name: sName,
hrefAppend: "/constructor",
hrefAppend: "#constructor",
text: sText
});
}
Expand Down Expand Up @@ -1974,14 +2009,14 @@ title="Information published on ${bSAPHosted ? '' : 'non '}SAP site" class="sapU

// Start the work here
let p = getLibraryPromise(oChainObject)
.then(extractComponentAndDocuindexUrl)
.then(flattenComponents)
.then(extractSamplesFromDocuIndex)
.then(getDependencyLibraryFilesList)
.then(getAPIJSONPromise)
.then(loadDependencyLibraryFiles)
.then(transformApiJson)
.then(createApiRefApiJson);
.then(extractComponentAndDocuindexUrl)
.then(flattenComponents)
.then(extractSamplesFromDocuIndex)
.then(getDependencyLibraryFilesList)
.then(getAPIJSONPromise)
.then(loadDependencyLibraryFiles)
.then(transformApiJson)
.then(createApiRefApiJson);
return p;

};
Expand Down
Loading

0 comments on commit c868fa0

Please sign in to comment.