JSDoc: configure destination path + refactor API signatures

lib/processors/jsdoc/jsdocGenerator.js

@@ -1,11 +1,11 @@
 const spawn = require("child_process").spawn;
-const fs = require("fs");
+const fs = require("graceful-fs");
 const path = require("path");
 const {promisify} = require("util");
 const writeFile = promisify(fs.writeFile);
 const {resourceFactory} = require("@ui5/fs");
 
-async function generateJsdocConfig({targetPath, namespace, libraryName, version, variants}) {
+async function generateJsdocConfig({targetPath, tmpPath, namespace, projectName, version, variants}) {
 	// Resolve path to this script to get the path to the JSDoc extensions folder
 	const jsdocPath = path.normalize(__dirname);
 
@@ -17,13 +17,14 @@ async function generateJsdocConfig({targetPath, namespace, libraryName, version,
 			"template": "${jsdocPath}/ui5/template",
 			"ui5": {
 				"saveSymbols": true
-			}
+			},
+			"destination": "${tmpPath}"
 		},
 		"templates": {
 			"ui5": {
 				"variants": ${JSON.stringify(variants)},
 				"version": "${version}",
-				"jsapiFile": "${targetPath}/libraries/${libraryName}.js",
+				"jsapiFile": "${targetPath}/libraries/${projectName}.js",
 				"apiJsonFolder": "${targetPath}/dependency-apis",
 				"apiJsonFile": "${targetPath}/test-resources/${namespace}/designtime/api.json"
 			}
@@ -67,34 +68,39 @@ async function buildJsdoc({sourcePath, configPath}) {
  * @public
  * @alias module:@ui5/builder.processors.jsdoc.jsdocGenerator
  * @param {Object} parameters Parameters
- * @param {string} parameters.sourcePath Resources
- * @param {string} parameters.targetPath Resources
+ * @param {string} parameters.sourcePath Path of the source files to be processed
+ * @param {string} parameters.targetPath Path to write any output files
+ * @param {string} parameters.tmpPath Path to write temporary and debug files
  * @param {Object} parameters.options Options
- * @param {string} parameters.options.libraryName Library name
- * @param {string} parameters.options.version Library version
+ * @param {string} parameters.options.projectName Project name
+ * @param {string} parameters.options.version Project version
  * @param {Array} [parameters.options.variants=["apijson"]] JSDoc variants to be built
  * @param {boolean} [parameters.options.sdkBuild=true] Whether additional SDK specific api.json resources shall be generated
  * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving with
  */
-module.exports = async function({sourcePath, targetPath, options}) {
-	if ( !options.libraryName ) {
-		throw new TypeError("Cannot execute JSDoc build without a library name");
+module.exports = async function({sourcePath, targetPath, tmpPath, options}) {
+	if (!sourcePath || !targetPath || !tmpPath || !options.projectName || !options.version) {
+		throw new Error("[jsdocGenerator]: One or more mandatory options not provided");
 	}
 
 	if (!options.variants || options.variants.length === 0) {
 		options.variants = ["apijson"];
 	}
-	const namespace = options.libraryName.replace(/\./g, "/");
+	if (options.sdkBuild === undefined) {
+		options.sdkBuild = true;
+	}
+	const namespace = options.projectName.replace(/\./g, "/");
 
 	const config = await generateJsdocConfig({
 		targetPath,
+		tmpPath,
 		namespace,
-		libraryName: options.libraryName,
+		projectName: options.projectName,
 		version: options.version,
 		variants: options.variants
 	});
 
-	const configPath = await writeJsdocConfig(sourcePath, config);
+	const configPath = await writeJsdocConfig(tmpPath, config);
 
 	await buildJsdoc({
 		sourcePath,
@@ -109,7 +115,7 @@ module.exports = async function({sourcePath, targetPath, options}) {
 	// create resources from the output files
 	return Promise.all([
 		fsTarget.byPath(`/test-resources/${namespace}/designtime/api.json`)
-		// fsTarget.byPath(`/libraries/${options.libraryName}.js`)
+		// fsTarget.byPath(`/libraries/${options.projectName}.js`)
 		// ]).then((res) => res.filter($=>$));
 	]);
 };

lib/tasks/generateJsdoc.js

@@ -1,4 +1,6 @@
 const path = require("path");
+const makeDir = require("make-dir");
+const fs = require("graceful-fs");
 const tmp = require("tmp");
 tmp.setGracefulCleanup();
 const jsdocGenerator = require("../processors/jsdoc/jsdocGenerator");
@@ -10,21 +12,31 @@ const {resourceFactory} = require("@ui5/fs");
  * @module builder/tasks/createDebugFiles
  * @param {Object} parameters Parameters
  * @param {DuplexCollection} parameters.workspace DuplexCollection to read and write files
- * @param {Object} [parameters.options] Options
- * @param {string} [parameters.options.pattern] Pattern to locate the files to be processed
+ * @param {Object} parameters.options Options
+ * @param {string} parameters.options.pattern Pattern to locate the files to be processed
+ * @param {string} parameters.options.projectName Project name
+ * @param {string} parameters.options.version Project version
+ * @param {boolean} [parameters.options.sdkBuild=true] Whether additional SDK specific api.json resources shall be generated
  * @returns {Promise<undefined>} Promise resolving with <code>undefined</code> once data has been written
  */
 module.exports = async function({workspace, options}) {
+	if (!options.projectName || !options.version || !options.pattern) {
+		throw new Error("[generateJsdoc]: One or more mandatory options not provided");
+	}
+
 	let allResources;
 	if (workspace.byGlobSource) { // API only available on duplex collections
 		allResources = await workspace.byGlobSource(options.pattern);
 	} else {
 		allResources = await workspace.byGlob(options.pattern);
 	}
 
-	const {path: tmpDirPath, cleanupCallback} = await createTmpWorkDir();
-	const tmpSourcePath = path.join(tmpDirPath, "src");
-	const tmpTargetPath = path.join(tmpDirPath, "target");
+	const {path: tmpDirPath, cleanupCallback} = await createTmpWorkDir(options.projectName);
+	const tmpSourcePath = path.join(tmpDirPath, "src"); // dir will be created by writing project resources below
+	const tmpTargetPath = path.join(tmpDirPath, "target"); // dir will be created by jsdoc itself
+	const tmpTmpPath = path.join(tmpDirPath, "tmp"); // dir needs to be created by us
+
+	await makeDir(tmpTmpPath, {fs});
 
 	const fsSource = resourceFactory.createAdapter({
 		fsBasePath: tmpSourcePath,
@@ -37,7 +49,12 @@ module.exports = async function({workspace, options}) {
 	const createdResources = await jsdocGenerator({
 		sourcePath: tmpSourcePath,
 		targetPath: tmpTargetPath,
-		options
+		tmpPath: tmpTmpPath,
+		options: {
+			projectName: options.projectName,
+			version: options.version,
+			variants: ["apijson"]
+		}
 	});
 
 	console.log(createdResources);
@@ -47,10 +64,10 @@ module.exports = async function({workspace, options}) {
 	}));
 };
 
-function createTmpWorkDir() {
+function createTmpWorkDir(projectName) {
 	return new Promise((resolve, reject) => {
 		tmp.dir({
-			prefix: "ui5-tooling-jsdoc-tmp-"
+			prefix: `ui5-tooling-tmp-jsdoc-${projectName}-`
 		}, (err, path, cleanupCallback) => {
 			if (err) {
 				reject(err);

lib/types/library/LibraryBuilder.js

@@ -45,12 +45,10 @@ class LibraryBuilder extends AbstractBuilder {
 			return generateJsdoc({
 				workspace: resourceCollections.workspace,
 				options: {
-					libraryName: project.metadata.name,
+					projectName: project.metadata.name,
 					version: project.version,
 					pattern: "/resources/**/*.js"
 				}
-			}).then(() => {
-				console.log("createJSDOC done");
 			});
 		});
 

package.json

@@ -103,6 +103,7 @@
 		"graceful-fs": "^4.1.15",
 		"jsdoc": "^3.5.5",
 		"less-openui5": "^0.6.0",
+		"make-dir": "^2.0.0",
 		"pretty-data": "^0.40.0",
 		"pretty-hrtime": "^1.0.3",
 		"replacestream": "^4.0.3",

test/lib/processors/jsdoc/jsdocGenerator.js

@@ -8,8 +8,9 @@ test("generateJsdocConfig", async (t) => {
 	const res = await jsdocGenerator._generateJsdocConfig({
 		sourcePath: "/some/source/path",
 		targetPath: "/some/target/path",
+		tmpPath: "/some/tmp/path",
 		namespace: "some/namespace",
-		libraryName: "some.namespace",
+		projectName: "some.namespace",
 		version: "1.0.0",
 		variants: ["apijson"]
 	});
@@ -25,7 +26,8 @@ test("generateJsdocConfig", async (t) => {
 			"template": "${jsdocGeneratorPath}/ui5/template",
 			"ui5": {
 				"saveSymbols": true
-			}
+			},
+			"destination": "/some/tmp/path"
 		},
 		"templates": {
 			"ui5": {
@@ -40,22 +42,22 @@ test("generateJsdocConfig", async (t) => {
 });
 
 test.serial("writeJsdocConfig", async (t) => {
-	mock("fs", {
+	mock("graceful-fs", {
 		writeFile: (configPath, configContent, callback) => {
 			t.deepEqual(configPath, "/some/path/jsdoc-config.json", "Correct config path supplied");
 			t.deepEqual(configContent, "some config", "Correct config content supplied");
 			callback();
 		}
 	});
-	mock.reRequire("fs");
+	mock.reRequire("graceful-fs");
 
 	// Re-require tested module
 	const jsdocGenerator = mock.reRequire("../../../../lib/processors/jsdoc/jsdocGenerator");
 	const res = await jsdocGenerator._writeJsdocConfig("/some/path", "some config");
 
 	t.deepEqual(res, "/some/path/jsdoc-config.json", "Correct config path returned");
 
-	mock.stop("fs");
+	mock.stop("graceful-fs");
 });
 
 test.serial("buildJsdoc", async (t) => {