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

[FIX] Align JSDoc template and scripts with OpenUI5 1.79 #460

Merged
merged 3 commits into from
May 19, 2020
Merged

[FIX] Align JSDoc template and scripts with OpenUI5 1.79 #460

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ddd3b3f
[INTERNAL] Align JSdoc template and scripts with OpenUI5 1.79
codeworrior May 18, 2020
a603004
[INTERNAL] Align JSdoc template and scripts with OpenUI5 1.79 regards…
flovogt May 19, 2020
a005fd6
[INTERNAL] adjust code style
flovogt May 19, 2020
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
76 changes: 71 additions & 5 deletions lib/processors/jsdoc/lib/createIndexFiles.js
View file
Open in desktop
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
Open in desktop
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