[WIP] Task to create JSDoc for a library, using the UI5 template/plugin

Note: the code is full of console.log just to track down an unexpected
      exit of the Node.js process.

lib/builder/builder.js

@@ -6,6 +6,7 @@ const definedTasks = {
  replaceCopyright: require("../tasks/replaceCopyright"),
  replaceVersion: require("../tasks/replaceVersion"),
  createDebugFiles: require("../tasks/createDebugFiles"),
+ createJSDoc: require("../tasks/createJSDoc"),
  uglify: require("../tasks/uglify"),
  buildThemes: require("../tasks/buildThemes"),
  generateVersionInfo: require("../tasks/generateVersionInfo"),

lib/processors/jsdoc/create-api-index.js

@@ -0,0 +1,270 @@
+/*
+ * Node script to create cross-library API index files for use in the UI5 SDKs.
+ *
+ * (c) Copyright 2009-2018 SAP SE or an SAP affiliate company.
+ * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
+ */
+
+"use strict";
+const fs = require("fs");
+const path = require("path");
+
+function process(versionInfoFile, unpackedTestresourcesRoot, targetFile, targetFileDeprecated, targetFileExperimental, targetFileSince) {
+
+ console.log("[INFO] creating API index files");
+ console.log("[INFO] sap-ui-version.json: " + versionInfoFile);
+ console.log("[INFO] unpacked test-resources: " + unpackedTestresourcesRoot);
+ console.log("[INFO] target file: " + targetFile);
+ console.log("[INFO] target file deprecated: " + targetFileDeprecated);
+ console.log("[INFO] target file experimental: " + targetFileExperimental);
+ console.log("[INFO] target file since: " + targetFileSince);
+ console.log("[INFO]");
+
+ // Deprecated, Experimental and Since collections
+ let oListCollection = {
+ deprecated: {
+ noVersion: {
+ apis: []
+ }
+ },
+ experimental: {
+ noVersion: {
+ apis: []
+ }
+ },
+ since: {
+ noVersion: {
+ apis: []
+ }
+ }
+ };
+
+ function readJSONFile(file) {
+ return new Promise(function (resolve, reject) {
+ fs.readFile(file, 'utf8', function (err, data) {
+ if (err) {
+ reject(err);
+ } else {
+ // Handle empty files scenario
+ if (data.trim() === "") {
+ resolve({});
+ } else {
+ resolve(JSON.parse(String(data)));
+ }
+ }
+ });
+ });
+ }
+
+ function mkdirSync(dir) {
+ if (dir && !fs.existsSync(dir)) {
+ mkdirSync( path.dirname(dir) );
+ fs.mkdirSync(dir);
+ }
+ }
+
+ function writeJSON(file, content) {
+ return new Promise(function(resolve,reject) {
+ // Create dir if it does not exist
+ mkdirSync( path.dirname(file) );
+ fs.writeFile(file, JSON.stringify(content), "utf-8", function(err) {
+ if ( err ) {
+ reject(err);
+ return;
+ }
+ resolve(true);
+ });
+ });
+ }
+
+ /*
+ * Extracts main symbol information from a library api.json.
+ * Also collects deprecated, experimental and since api's.
+ * Returns a promise that resolves with an array of symbols.
+ */
+ function createSymbolSummaryForLib(lib) {
+ let 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 => {
+ collectLists(symbol);
+ return {
+ name: symbol.name,
+ kind: symbol.kind,
+ visibility: symbol.visibility,
+ extends: symbol.extends,
+ implements: symbol.implements,
+ lib: lib
+ };
+ });
+ })
+ }
+
+ /*
+ * Collects Deprecated, Experimental and Since data from passed symbol
+ * including symbol itself, methods and events.
+ */
+ function collectLists(oSymbol) {
+
+ function addData(oDataType, oEntityObject, sObjectType, sSymbolName) {
+ let sSince = oDataType !== "since" ? oEntityObject[oDataType].since : oEntityObject.since,
+ oData = {
+ control: sSymbolName,
+ text: oEntityObject[oDataType].text || oEntityObject.description,
+ type: sObjectType,
+ "static": !!oEntityObject.static,
+ visibility: oEntityObject.visibility
+ };
+
+ // For class we skip entityName
+ if (sObjectType !== "class") {
+ oData.entityName = oEntityObject.name;
+ }
+
+ if (sSince) {
+ // take only major and minor versions
+ let sVersion = sSince.split(".").slice(0, 2).join(".");
+
+ oData.since = sSince;
+
+ if (!oListCollection[oDataType][sVersion]) {
+ oListCollection[oDataType][sVersion] = {
+ name: sVersion,
+ apis: []
+ };
+ }
+
+ oListCollection[oDataType][sVersion].apis.push(oData);
+ } else {
+ oListCollection[oDataType].noVersion.apis.push(oData);
+ }
+ }
+
+ // Classes
+ if (oSymbol.deprecated) {
+ addData("deprecated", oSymbol, "class", oSymbol.name);
+ }
+
+ if (oSymbol.experimental) {
+ addData("experimental", oSymbol, "class", oSymbol.name);
+ }
+
+ if (oSymbol.since) {
+ addData("since", oSymbol, "class", oSymbol.name);
+ }
+
+ // Methods
+ oSymbol.methods && oSymbol.methods.forEach(oMethod => {
+ if (oMethod.deprecated) {
+ addData("deprecated", oMethod, "methods", oSymbol.name);
+ }
+
+ if (oMethod.experimental) {
+ addData("experimental", oMethod, "methods", oSymbol.name);
+ }
+
+ if (oMethod.since) {
+ addData("since", oMethod, "methods", oSymbol.name);
+ }
+ });
+
+ // Events
+ oSymbol.events && oSymbol.events.forEach(oEvent => {
+ if (oEvent.deprecated) {
+ addData("deprecated", oEvent, "events", oSymbol.name);
+ }
+
+ if (oEvent.experimental) {
+ addData("experimental", oEvent, "events", oSymbol.name);
+ }
+
+ if (oEvent.since) {
+ addData("since", oEvent, "events", oSymbol.name);
+ }
+ });
+
+ }
+
+ function deepMerge(arrayOfArrays) {
+ return arrayOfArrays.reduce((array, items) => {
+ array.push.apply(array, items);
+ return array;
+ }, []);
+ }
+
+ function expandHierarchyInfo(symbols) {
+ let byName = new Map();
+ symbols.forEach(symbol => {
+ byName.set(symbol.name, symbol);
+ });
+ symbols.forEach(symbol => {
+ let parent = symbol.extends && byName.get(symbol.extends);
+ if (parent) {
+ parent.extendedBy = parent.extendedBy ||  [];
+ parent.extendedBy.push(symbol.name);
+ }
+ if (symbol.implements) {
+ symbol.implements.forEach(intfName => {
+ let intf = byName.get(intfName);
+ if (intf) {
+ intf.implementedBy = intf.implementedBy ||  [];
+ intf.implementedBy.push(symbol.name);
+ }
+ });
+ }
+ });
+ return symbols;
+ }
+
+ function createOverallIndex() {
+ let version = "0.0.0";
+
+ var p = readJSONFile(versionInfoFile)
+ .then(versionInfo => {
+ version = versionInfo.version;
+ return Promise.all(
+ versionInfo.libraries.map(
+ 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 [];
+ }
+ throw err;
+ })
+ )
+ );
+ })
+ .then(deepMerge)
+ .then(expandHierarchyInfo)
+ .then(symbols => {
+ let result = {
+ "$schema-ref": "http://schemas.sap.com/sapui5/designtime/api.json/1.0",
+ version: version,
+ library: "*",
+ symbols: symbols
+ };
+ return writeJSON(targetFile, result);
+ })
+ .then(() => Promise.all([
+ // write deprecated, experimental and since collections in the respective index files
+ writeJSON(targetFileDeprecated, oListCollection.deprecated),
+ writeJSON(targetFileExperimental, oListCollection.experimental),
+ writeJSON(targetFileSince, oListCollection.since)
+ ]))
+ .catch(err => {
+ console.error("**** failed to create API index for libraries:", err)
+ throw err;
+ });
+
+ return p;
+ }
+
+ return createOverallIndex();
+
+}
+
+module.exports = process;

lib/processors/jsdoc/dummy-child.js

@@ -0,0 +1,5 @@
+console.log('child executing');
+setTimeout(function() {
+ console.log("child done");
+ //process.exit(0);
+},20000);

lib/processors/jsdoc/jsdoc-config-template.json

@@ -0,0 +1,23 @@
+{
+ "source": {
+ "excludePattern": "(/|\\\\)library-all\\.js|(/|\\\\).*-preload\\.js|^jquery-.*\\.js|^sap-.*\\.js"
+ },
+ "opts" : {
+ "recurse": true,
+ "template" : "lib/jsdoc/ui5/template"
+ },
+ "plugins": [
+ "lib/jsdoc/ui5/plugin.js"
+ ],
+ "templates" : {
+ "ui5" : {
+ "variants": [
+ "apijson"
+ ],
+ "version": "${version}",
+ "apiJsonFolder": "${apiJsonFolder}",
+ "apiJsonFile": "${apiJsonFile}",
+ "includeSettingsInConstructor": false
+ }
+ }
+}