[INTERNAL] JSDoc: Refactor to use module: syntax and fix various docs

.eslintrc.js

@@ -56,7 +56,7 @@ module.exports = {
         "jsdoc/require-returns": 0,
         "jsdoc/require-returns-description": 0,
         "jsdoc/require-returns-type": 2,
-        "jsdoc/valid-types": 2
+        "jsdoc/valid-types": 0
     },
     "settings": {
         "jsdoc": {

index.js

@@ -6,7 +6,8 @@ module.exports = {
 	builder: require("./lib/builder/builder"),
 	/**
 	 * @public
-	 * @see @ui5/builder.processors
+	 * @see module:@ui5/builder.processors
+	 * @namespace
 	 */
 	processors: {
 		flexChangesBundler: require("./lib/processors/bundlers/flexChangesBundler"),
@@ -22,7 +23,8 @@ module.exports = {
 	},
 	/**
 	 * @public
-	 * @see @ui5/builder.tasks
+	 * @see module:@ui5/builder.tasks
+	 * @namespace
 	 */
 	tasks: {
 		generateComponentPreload: require("./lib/tasks/bundlers/generateComponentPreload"),
@@ -42,7 +44,8 @@ module.exports = {
 	},
 	/**
 	 * @private
-	 * @see @ui5/builder.types
+	 * @see module:@ui5/builder.types
+	 * @namespace
 	 */
 	types: {
 		AbstractBuilder: require("./lib/types/AbstractBuilder"),
@@ -53,15 +56,3 @@ module.exports = {
 	}
 };
 
-/**
- * @public
- * @namespace @ui5/builder.processors
- */
-/**
- * @public
- * @namespace @ui5/builder.tasks
- */
-/**
- * @private
- * @namespace @ui5/builder.types
- */

lib/builder/builder.js

@@ -25,121 +25,6 @@ function getElapsedTime(startTime) {
 	return prettyHrtime(timeDiff);
 }
 
-/**
- * Configures the project build and starts it.
- *
- * @public
- * @alias @ui5/builder.builder
- * @param {Object} parameters Parameters
- * @param {Object} parameters.tree Dependency tree
- * @param {string} parameters.destPath Target path
- * @param {boolean} [parameters.buildDependencies=false] Decides whether project dependencies are built as well
- * @param {boolean} [parameters.dev=false] Decides whether a development build should be activated (skips non-essential and time-intensive tasks)
- * @param {boolean} [parameters.selfContained=false] Flag to activate self contained build
- * @param {Array} [parameters.includedTasks=[]] List of tasks to be included
- * @param {Array} [parameters.excludedTasks=[]] List of tasks to be excluded. If the wildcard '*' is provided, only the included tasks will be executed.
- * @param {Array} [parameters.devExcludeProject=[]] List of projects to be excluded from development build
- * @returns {Promise} Promise resolving to <code>undefined</code> once build has finished
- */
-function build({tree, destPath, buildDependencies = false, dev = false, selfContained = false, includedTasks = [], excludedTasks = [], devExcludeProject = []}) {
-	const startTime = process.hrtime();
-	log.info(`Building project ${tree.metadata.name}` + (buildDependencies ? "" : " not") +
-		" including dependencies..." + (dev ? " [dev mode]" : ""));
-	log.verbose(`Building to ${destPath}...`);
-
-	const selectedTasks = composeTaskList({dev, selfContained, includedTasks, excludedTasks});
-
-	const fsTarget = resourceFactory.createAdapter({
-		fsBasePath: destPath,
-		virBasePath: "/"
-	});
-
-
-	const projects = {}; // Unique project index to prevent building the same project multiple times
-
-	const projectCountMarker = {};
-	function projectCount(project, count = 0) {
-		if (buildDependencies) {
-			count = project.dependencies.reduce((depCount, depProject) => {
-				return projectCount(depProject, depCount);
-			}, count);
-		}
-		if (!projectCountMarker[project.metadata.name]) {
-			count++;
-			projectCountMarker[project.metadata.name] = true;
-		}
-		return count;
-	}
-	const iProjectCount = projectCount(tree);
-	const buildLogger = log.createTaskLogger("🛠 ", iProjectCount);
-
-	function buildProject(project) {
-		let depPromise;
-		let projectTasks = selectedTasks;
-		if (buildDependencies) {
-			// Build dependencies in sequence as it is far easier to detect issues and reduces
-			// side effects or other issues such as too many open files
-			depPromise = project.dependencies.reduce(function(p, depProject) {
-				return p.then(() => buildProject(depProject));
-			}, Promise.resolve());
-		} else {
-			depPromise = Promise.resolve();
-		}
-		// Build the project after all dependencies have been built
-		return depPromise.then(() => {
-			if (projects[project.metadata.name]) {
-				return Promise.resolve();
-			} else {
-				projects[project.metadata.name] = true;
-			}
-			buildLogger.startWork(`Building project ${project.metadata.name}`);
-
-			const projectType = typeRepository.getType(project.type);
-			const resourceCollections = resourceFactory.createCollectionsForTree(project, {
-				useNamespaces: true
-			});
-
-			const workspace = resourceFactory.createWorkspace({
-				reader: resourceCollections.source,
-				name: project.metadata.name
-			});
-
-			if (dev && devExcludeProject.indexOf(project.metadata.name) !== -1) {
-				projectTasks = composeTaskList({dev: false, selfContained, includedTasks, excludedTasks});
-			}
-			return projectType.build({
-				resourceCollections: {
-					workspace,
-					dependencies: resourceCollections.dependencies
-				},
-				tasks: projectTasks,
-				project,
-				parentLogger: log
-			}).then(() => {
-				log.verbose("Finished building project %s. Writing out files...", project.metadata.name);
-				buildLogger.completeWork(1);
-
-				return workspace.byGlob("/**/*.*").then((resources) => {
-					return Promise.all(resources.map((resource) => {
-						if (project === tree && project.metadata.namespace) {
-							// Root-project only: Remove namespace prefix if given
-							resource.setPath(resource.getPath().replace(
-								new RegExp(`^/resources/${project.metadata.namespace}`), ""));
-						}
-						return fsTarget.write(resource);
-					}));
-				});
-			});
-		});
-	}
-
-	return buildProject(tree).then(() => {
-		log.info(`Build succeeded in ${getElapsedTime(startTime)}`);
-	}, (err) => {
-		log.error(`Build failed in ${getElapsedTime(startTime)}`);
-		throw err;
-	});
-}
 /**
  * Creates the list of tasks to be executed by the build process
  *
@@ -218,7 +103,132 @@ function composeTaskList({dev, selfContained, includedTasks, excludedTasks}) {
 	return selectedTasks;
 }
 
+/**
+ * Builder
+ *
+ * @public
+ * @namespace
+ * @alias module:@ui5/builder.builder
+ */
 module.exports = {
-	build: build,
-	tasks: definedTasks
+	tasks: definedTasks,
+
+	/**
+	 * Configures the project build and starts it.
+	 *
+	 * @public
+	 * @param {Object} parameters Parameters
+	 * @param {Object} parameters.tree Dependency tree
+	 * @param {string} parameters.destPath Target path
+	 * @param {boolean} [parameters.buildDependencies=false] Decides whether project dependencies are built as well
+	 * @param {boolean} [parameters.dev=false] Decides whether a development build should be activated (skips non-essential and time-intensive tasks)
+	 * @param {boolean} [parameters.selfContained=false] Flag to activate self contained build
+	 * @param {Array} [parameters.includedTasks=[]] List of tasks to be included
+	 * @param {Array} [parameters.excludedTasks=[]] List of tasks to be excluded. If the wildcard '*' is provided, only the included tasks will be executed.
+	 * @param {Array} [parameters.devExcludeProject=[]] List of projects to be excluded from development build
+	 * @returns {Promise} Promise resolving to <code>undefined</code> once build has finished
+	 */
+	build({
+		tree, destPath,
+		buildDependencies = false, dev = false, selfContained = false,
+		includedTasks = [], excludedTasks = [], devExcludeProject = []
+	}) {
+		const startTime = process.hrtime();
+		log.info(`Building project ${tree.metadata.name}` + (buildDependencies ? "" : " not") +
+			" including dependencies..." + (dev ? " [dev mode]" : ""));
+		log.verbose(`Building to ${destPath}...`);
+
+		const selectedTasks = composeTaskList({dev, selfContained, includedTasks, excludedTasks});
+
+		const fsTarget = resourceFactory.createAdapter({
+			fsBasePath: destPath,
+			virBasePath: "/"
+		});
+
+
+		const projects = {}; // Unique project index to prevent building the same project multiple times
+
+		const projectCountMarker = {};
+		function projectCount(project, count = 0) {
+			if (buildDependencies) {
+				count = project.dependencies.reduce((depCount, depProject) => {
+					return projectCount(depProject, depCount);
+				}, count);
+			}
+			if (!projectCountMarker[project.metadata.name]) {
+				count++;
+				projectCountMarker[project.metadata.name] = true;
+			}
+			return count;
+		}
+		const iProjectCount = projectCount(tree);
+		const buildLogger = log.createTaskLogger("🛠 ", iProjectCount);
+
+		function buildProject(project) {
+			let depPromise;
+			let projectTasks = selectedTasks;
+			if (buildDependencies) {
+				// Build dependencies in sequence as it is far easier to detect issues and reduces
+				// side effects or other issues such as too many open files
+				depPromise = project.dependencies.reduce(function(p, depProject) {
+					return p.then(() => buildProject(depProject));
+				}, Promise.resolve());
+			} else {
+				depPromise = Promise.resolve();
+			}
+			// Build the project after all dependencies have been built
+			return depPromise.then(() => {
+				if (projects[project.metadata.name]) {
+					return Promise.resolve();
+				} else {
+					projects[project.metadata.name] = true;
+				}
+				buildLogger.startWork(`Building project ${project.metadata.name}`);
+
+				const projectType = typeRepository.getType(project.type);
+				const resourceCollections = resourceFactory.createCollectionsForTree(project, {
+					useNamespaces: true
+				});
+
+				const workspace = resourceFactory.createWorkspace({
+					reader: resourceCollections.source,
+					name: project.metadata.name
+				});
+
+				if (dev && devExcludeProject.indexOf(project.metadata.name) !== -1) {
+					projectTasks = composeTaskList({dev: false, selfContained, includedTasks, excludedTasks});
+				}
+				return projectType.build({
+					resourceCollections: {
+						workspace,
+						dependencies: resourceCollections.dependencies
+					},
+					tasks: projectTasks,
+					project,
+					parentLogger: log
+				}).then(() => {
+					log.verbose("Finished building project %s. Writing out files...", project.metadata.name);
+					buildLogger.completeWork(1);
+
+					return workspace.byGlob("/**/*.*").then((resources) => {
+						return Promise.all(resources.map((resource) => {
+							if (project === tree && project.metadata.namespace) {
+								// Root-project only: Remove namespace prefix if given
+								resource.setPath(resource.getPath().replace(
+									new RegExp(`^/resources/${project.metadata.namespace}`), ""));
+							}
+							return fsTarget.write(resource);
+						}));
+					});
+				});
+			});
+		}
+
+		return buildProject(tree).then(() => {
+			log.info(`Build succeeded in ${getElapsedTime(startTime)}`);
+		}, (err) => {
+			log.error(`Build failed in ${getElapsedTime(startTime)}`);
+			throw err;
+		});
+	}
 };

lib/lbt/analyzer/analyzeLibraryJS.js

@@ -83,7 +83,7 @@ async function analyze(resource) {
  *
  * Note: only the first initLibrary() call that is found with a DFS on the AST, will be evaluated.
  *
- * @param {Resource} resource library.js resource whose content should be analyzed
+ * @param {module:@ui5/fs.Resource} resource library.js resource whose content should be analyzed
  * @returns {Promise<Object>} A Promise on the extract info object
  */
 module.exports = function(resource) {

lib/processors/bundlers/flexChangesBundler.js

@@ -5,12 +5,12 @@ const resourceFactory = require("@ui5/fs").resourceFactory;
  * Bundles all supplied changes.
  *
  * @public
- * @alias @ui5/builder.processors.flexChangesBundler
+ * @alias module:@ui5/builder.processors.flexChangesBundler
  * @param {Object} parameters Parameters
- * @param {Resource[]} parameters.resources List of resources to be processed
+ * @param {module:@ui5/fs.Resource[]} parameters.resources List of resources to be processed
  * @param {Object} parameters.options Options
  * @param {string} parameters.options.pathPrefix Prefix for bundle path
- * @returns {Promise<Resource[]>} Promise resolving with flexchange bundle resources
+ * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving with flexchange bundle resources
  */
 module.exports = function({resources, options}) {
 	const layers = {

lib/processors/bundlers/manifestBundler.js

@@ -19,7 +19,7 @@ class I18nResourceList {
 	 * Adds a i18n resource to the repository
 	 *
 	 * @param {string} directory Path to the i18n resource
-	 * @param {Resource} resource i18n resource
+	 * @param {module:@ui5/fs.Resource} resource i18n resource
 	 */
 	add(directory, resource) {
 		const normalizedDirectory = path.normalize(directory);
@@ -43,16 +43,16 @@ class I18nResourceList {
 /**
  * Creates a manifest bundle from the provided resources.
  *
- * @alias @ui5/builder.processors.manifestBundler
+ * @alias module:@ui5/builder.processors.manifestBundler
  * @public
  * @param {Object} parameters Parameters
- * @param {Resource[]} parameters.resources List of resources to be processed
+ * @param {module:@ui5/fs.Resource[]} parameters.resources List of resources to be processed
  * @param {Object} parameters.options Options
  * @param {string} parameters.options.namespace Namespace of the project
  * @param {string} parameters.options.bundleName Name of the bundled zip file
  * @param {string} parameters.options.propertiesExtension Extension name of the properties files
  * @param {string} parameters.options.descriptor Descriptor name
- * @returns {Promise<Resource[]>} Promise resolving with manifest bundle resources
+ * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving with manifest bundle resources
  */
 module.exports = ({resources, options}) => {
 	function getDescriptorI18nInfo(manifest) {

lib/processors/bundlers/moduleBundler.js

@@ -41,13 +41,13 @@ class LocatorResourcePool extends ResourcePool {
  * Legacy preload bundler.
  *
  * @public
- * @alias @ui5/builder.processors.moduleBundler
+ * @alias module:@ui5/builder.processors.moduleBundler
  * @param {Object} parameters Parameters
- * @param {Resource[]} parameters.resources Resources
+ * @param {module:@ui5/fs.Resource[]} parameters.resources Resources
  * @param {Object} parameters.options Options
  * @param {Object} parameters.options.bundleDefinition Module bundle definition
  * @param {Object} parameters.options.bundleOptions Module bundle options
- * @returns {Promise<Resource[]>} Promise resolving with module bundle resources
+ * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving with module bundle resources
  */
 module.exports = function({resources, options}) {
 //	console.log("preloadBundler bundleDefinition:");

lib/processors/debugFileCreator.js

@@ -5,10 +5,10 @@ const util = require("util");
  * Creates *-dbg.js files for all supplied resources.
  *
  * @public
- * @alias @ui5/builder.processors.debugFileCreator
+ * @alias module:@ui5/builder.processors.debugFileCreator
  * @param {Object} parameters Parameters
- * @param {Resource[]} parameters.resources List of resources to be processed
- * @returns {Promise<Resource[]>} Promise resolving with debug resources
+ * @param {module:@ui5/fs.Resource[]} parameters.resources List of resources to be processed
+ * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving with debug resources
  */
 module.exports = function({resources, fs}) {
 	const options = {