JSDoc cleanup

Author: RandomByte

lib/graph/Module.js

@@ -80,6 +80,21 @@ class Module {
 		return this._modulePath;
 	}
 
+	/**
+	 * Specifications found in the module
+	 *
+	 * @public
+	 * @typedef {object} SpecificationsResult
+	 * @property {@ui5/project.specifications.Project|undefined} Project found in the module (if one is found)
+	 * @property {@ui5/project.specifications.Extension[]} Array of extensions found in the module
+	 *
+	 */
+
+	/**
+	 * Get any available project and extensions of the module
+	 *
+	 * @returns {SpecificationsResult} Project and extensions found in the module
+	 */
 	async getSpecifications() {
 		if (this._pGetSpecifications) {
 			return this._pGetSpecifications;

lib/graph/ProjectGraph.js

@@ -27,6 +27,10 @@ class ProjectGraph {
 		this._shouldResolveOptionalDependencies = false; // Performance optimization flag
 	}
 
+	/**
+	 * @public
+	 * @returns {module:@ui5/project.specification.Project} Root project
+	 */
 	getRoot() {
 		const rootProject = this._projects[this._rootProjectName];
 		if (!rootProject) {
@@ -224,9 +228,14 @@ class ProjectGraph {
 	}
 
 	/**
+	 * Transforms any optional dependencies in the graph for which the target is referenced by
+	 * at least one non-optional project
+	 * into a non-optional dependency.
+	 *
 	 * @public
 	 */
 	resolveOptionalDependencies() {
+		// TODO: If a project is referenced as non-optional by an *optional* dependency, it should still be optional
 		if (!this._shouldResolveOptionalDependencies) {
 			log.verbose(`Skipping resolution of optional dependencies since none have been declared`);
 			return;

lib/graph/projectGraphBuilder.js

@@ -24,17 +24,43 @@ function _handleExtensions(graph, shimCollection, extensions) {
 }
 
 /**
- * Tree node
+ * Dependency graph node representing a module
  *
  * @public
- * @typedef {object} TreeNode
+ * @typedef {object} Node
  * @property {string} node.id Unique ID for the project
  * @property {string} node.version Version of the project
  * @property {string} node.path File System path to access the projects resources
  * @property {object|object[]} [node.configuration]
  *	Configuration object or array of objects to use instead of reading from a configuration file
  * @property {string} [node.configPath] Configuration file to use instead the default ui5.yaml
- * @property {TreeNode[]} dependencies
+ * @property {boolean} [node.optional]
+ *					Whether the node is an optional dependency of the parent it has been requested for
+ * @property {*} * Additional attributes are allowed but ignored.
+ *					These can be used to pass information internally in the provider.
+ */
+
+/**
+ * Node Provider interface
+ *
+ * @interface NodeProvider
+ */
+
+/**
+ * Retrieve information on the root module
+ *
+ * @function
+ * @name NodeProvider#getRootNode
+ * @returns {Node} The root node of the dependency graph
+ */
+
+/**
+ * Retrieve information on given a nodes dependencies
+ *
+ * @function
+ * @name NodeProvider#getDependencies
+ * @param {Node} The root node of the dependency graph
+ * @returns {Node[]} Array of nodes which are direct dependencies of the given node
  */
 
 /**
@@ -43,7 +69,7 @@ function _handleExtensions(graph, shimCollection, extensions) {
  *
  * @public
  * @alias module:@ui5/project.graph.projectGraphBuilder
- * @param {ModuleProvider} nodeProvider Dependency tree as returned by a translator
+ * @param {NodeProvider} nodeProvider
  * @returns {module:@ui5/project.graph.ProjectGraph} A new project graph instance
  */
 module.exports = async function(nodeProvider) {

lib/specifications/Configuration.js

@@ -51,21 +51,30 @@ class Project extends Specification {
 
 	/* === Resource Access === */
 	/**
+	* Get a resource reader for the sources of the project (excluding any test resources)
+	*
 	* @public
+	 * @returns {module:@ui5/fs.ReaderCollection} Reader collection
 	*/
 	getSourceReader() {
 		throw new Error(`getSourceReader must be implemented by subclass ${this.constructor.name}`);
 	}
 
 	/**
+	* Get a resource reader for accessing the project resources the same way the UI5 runtime would do
+	*
 	* @public
+	* @returns {module:@ui5/fs.ReaderCollection} Reader collection
 	*/
 	getRuntimeReader() {
 		throw new Error(`getRuntimeReader must be implemented by subclass ${this.constructor.name}`);
 	}
 
 	/**
+	* Get a resource reader for accessing the project resources during the build process
+	*
 	* @public
+	* @returns {module:@ui5/fs.ReaderCollection} Reader collection
 	*/
 	getBuildtimeReader() {
 		throw new Error(`getBuildtimeReader must be implemented by subclass ${this.constructor.name}`);

lib/specifications/Project.js

@@ -130,7 +130,10 @@ class Specification {
 
 	/* === Resource Access === */
 	/**
+	* Get a resource reader for the root directory of the project
+	*
 	* @public
+	* @returns {module:@ui5/fs.ReaderCollection} Reader collection
 	*/
 	getRootReader() {
 		return resourceFactory.createReader({