[INTERNAL] JSDoc: Make API private by default

.eslintrc.js

@@ -7,6 +7,9 @@ module.exports = {
         "ecmaVersion": 8
     },
     "extends": ["eslint:recommended", "google"],
+    "plugins": [
+        "jsdoc"
+    ],
     "rules": {
         "indent": [
             "error",
@@ -35,15 +38,32 @@ module.exports = {
         ],
         "comma-dangle": "off",
         "no-tabs": "off",
-        'valid-jsdoc': [
-            2,
-            {
-                requireParamDescription: false,
-                requireReturnDescription: false,
-                requireReturn: false,
-                prefer: {return: 'returns'},
+        "valid-jsdoc": 0,
+        "jsdoc/check-examples": 2,
+        "jsdoc/check-param-names": 2,
+        "jsdoc/check-tag-names": 2,
+        "jsdoc/check-types": 2,
+        "jsdoc/newline-after-description": 2,
+        "jsdoc/no-undefined-types": 0,
+        "jsdoc/require-description": 0,
+        "jsdoc/require-description-complete-sentence": 0,
+        "jsdoc/require-example": 0,
+        "jsdoc/require-hyphen-before-param-description": 0,
+        "jsdoc/require-param": 2,
+        "jsdoc/require-param-description": 0,
+        "jsdoc/require-param-name": 2,
+        "jsdoc/require-param-type": 2,
+        "jsdoc/require-returns": 0,
+        "jsdoc/require-returns-description": 0,
+        "jsdoc/require-returns-type": 2,
+        "jsdoc/valid-types": 0
+    },
+    "settings": {
+        "jsdoc": {
+            "tagNamePreference": {
+                "return": "returns"
             }
-        ],
+        }
     },
     "root": true
 };

docs/BuildExtensibility.md

@@ -18,15 +18,15 @@ In the below example, when building the library `my.library` the `babel` task wi
 specVersion: "0.1"
 type: library
 metadata:
-    name: my.library
+	name: my.library
 builder:
-    customTasks:
-    - name: babel
-      beforeTask: generateComponentPreload
-    - name: generateMarkdownFiles
-      afterTask: uglify
-      configuration:
-        color: blue
+	customTasks:
+	- name: babel
+	  beforeTask: generateComponentPreload
+	- name: generateMarkdownFiles
+	  afterTask: uglify
+	  configuration:
+		color: blue
 ````
 
 ### Example: Connect multiple custom tasks
@@ -39,13 +39,13 @@ You can also connect multiple custom task with each other. Please be aware that
 specVersion: "0.1"
 type: library
 metadata:
-    name: my.library
+	name: my.library
 builder:
-    customTasks:
-    - name: myCustomTask1
-      beforeTask: generateComponentPreload
-    - name: myCustomTask2
-      afterTask: myCustomTask1
+	customTasks:
+	- name: myCustomTask1
+	  beforeTask: generateComponentPreload
+	- name: myCustomTask2
+	  afterTask: myCustomTask1
 ````
 
 ## Custom Task Extension
@@ -60,9 +60,9 @@ specVersion: "0.1"
 kind: extension
 type: task
 metadata:
-    name: generateMarkdownFiles
+	name: generateMarkdownFiles
 task:
-    path: lib/tasks/generateMarkdownFiles.js
+	path: lib/tasks/generateMarkdownFiles.js
 ````
 
 Task extensions can be **standalone modules** which are handled as dependencies.
@@ -80,22 +80,22 @@ specVersion: "0.1"
 kind: project
 type: library
 metadata:
-    name: my.library
+	name: my.library
 builder:
-    customTasks:
-    - name: generateMarkdownFiles
-      afterTask: uglify
-      configuration:
-        color: blue
+	customTasks:
+	- name: generateMarkdownFiles
+	  afterTask: uglify
+	  configuration:
+		color: blue
 ---
 # Task extension as part of your project
 specVersion: "0.1"
 kind: extension
 type: task
 metadata:
-    name: generateMarkdownFiles
+	name: generateMarkdownFiles
 task:
-    path: lib/tasks/generateMarkdownFiles.js
+	path: lib/tasks/generateMarkdownFiles.js
 ````
 
 ## Task Implementation
@@ -107,15 +107,15 @@ A custom task implementation needs to return a function with the following signa
  * Custom task example
  *
  * @param {Object} parameters Parameters
- * @param {DuplexCollection} parameters.workspace DuplexCollection to read and write files
- * @param {AbstractReader} parameters.dependencies Reader or Collection to read dependency files
+ * @param {module:@ui5/fs.DuplexCollection} parameters.workspace DuplexCollection to read and write files
+ * @param {module:@ui5/fs.AbstractReader} parameters.dependencies Reader or Collection to read dependency files
  * @param {Object} parameters.options Options
  * @param {string} parameters.options.projectName Project name
  * @param {string} [parameters.options.configuration] Task configuration if given in ui5.yaml
  * @returns {Promise<undefined>} Promise resolving with undefined once data has been written
  */
 module.exports = function({workspace, options}) {
-    // [...]
+	// [...]
 };
 ````
 
@@ -128,16 +128,16 @@ The following code snippets shows an example how a task implementation could loo
 const markdownGenerator = require("./markdownGenerator");
 
 module.exports = function({workspace, options}) {
-    return workspace.byGlob("**/*.txt")
-        .then((textResources) => {
-            return markdownGenerator({
-                resources: textResources
-            });
-        })
-        .then((markdownResources) => {
-            return Promise.all(markdownResources.map((resource) => {
-                return workspace.write(resource);
-            }));
-        });
+	return workspace.byGlob("**/*.txt")
+		.then((textResources) => {
+			return markdownGenerator({
+				resources: textResources
+			});
+		})
+		.then((markdownResources) => {
+			return Promise.all(markdownResources.map((resource) => {
+				return workspace.write(resource);
+			}));
+		});
 };
-````
+````

index.js

@@ -1,10 +1,17 @@
-const ui5Project = {
+/**
+ * @module module:@ui5/project
+ * @public
+ */
+module.exports = {
 	normalizer: require("./lib/normalizer"),
 	projectPreprocessor: require("./lib/projectPreprocessor"),
+	/**
+	 * @private
+	 * @see module:@ui5/project.translators
+	 * @namespace
+	 */
 	translators: {
 		"npm": require("./lib/translators/npm"),
 		"static": require("./lib/translators/static")
 	}
 };
-
-module.exports = ui5Project;

jsdoc.json

@@ -1,9 +1,9 @@
 {
     "tags": {
-        "allowUnknownTags": true
+        "allowUnknownTags": false
     },
     "source": {
-        "include": ["README.md"],
+        "include": ["README.md", "index.js"],
         "includePattern": ".+\\.js$",
         "excludePattern": "(node_modules(\\\\|/))"
     },
@@ -13,10 +13,48 @@
         "encoding": "utf8",
         "destination": "jsdocs/",
         "recurse": true,
-        "verbose": true
+        "verbose": true,
+        "access": "public"
     },
     "templates": {
         "cleverLinks": false,
-        "monospaceLinks": false
+        "monospaceLinks": false,
+        "default": {
+            "useLongnameInNav": true
+        }
+    },
+    "openGraph": {
+        "title": "UI5 Build and Development Tooling - API Reference",
+        "type": "website",
+        "image": "https://sap.github.io/ui5-tooling/docs/images/UI5_logo_wide.png",
+        "site_name": "UI5 Build and Development Tooling - API Reference",
+        "url": "https://sap.github.io/ui5-tooling/"
+    },
+    "docdash": {
+        "sectionOrder": [
+            "Modules",
+            "Namespaces",
+            "Classes",
+            "Externals",
+            "Events",
+            "Mixins",
+            "Tutorials",
+            "Interfaces"
+        ],
+        "meta": {
+            "title": "UI5 Build and Development Tooling - API Reference - UI5 Project",
+            "description": "UI5 Build and Development Tooling - API Reference - UI5 Project",
+            "keyword": "openui5 sapui5 ui5 build development tool api reference"
+        },
+        "search": true,
+        "wrap": true,
+        "menu": {
+            "GitHub": {
+                "href": "https://github.com/SAP/ui5-project",
+                "target": "_blank",
+                "class": "menu-item",
+                "id": "github_link"
+            }
+        }
     }
 }

lib/normalizer.js

@@ -3,19 +3,23 @@ const projectPreprocessor = require("./projectPreprocessor");
 
 
 /**
- * Generate project and dependency trees via translators. Optionally configure all projects with the projectPreprocessor.
+ * Generate project and dependency trees via translators.
+ * Optionally configure all projects with the projectPreprocessor.
  *
- * @module normalizer/normalizer
+ * @public
+ * @namespace
+ * @alias module:@ui5/project.normalizer
  */
 const Normalizer = {
 	/**
 	 * Generates a project and dependency tree via translators and configures all projects via the projectPreprocessor
 	 *
+	 * @public
 	 * @param {Object} [options]
 	 * @param {string} [options.cwd] Current working directory
 	 * @param {string} [options.configPath] Path to configuration file
 	 * @param {string} [options.translator] Translator to use
-	 * @returns {Promise} Promise resolving to tree object
+	 * @returns {Promise<Object>} Promise resolving to tree object
 	 */
 	generateProjectTree: async function(options = {}) {
 		const tree = await Normalizer.generateDependencyTree(options);
@@ -29,11 +33,12 @@ const Normalizer = {
 	/**
 	 * Generates a project and dependency tree via translators
 	 *
+	 * @public
 	 * @param {Object} [options]
 	 * @param {string} [options.cwd=.] Current working directory
 	 * @param {string} [options.translator=npm] Translator to use
-	 * @param {object} [options.translatorOptions] Options to pass to translator
-	 * @returns {Promise} Promise resolving to tree object
+	 * @param {Object} [options.translatorOptions] Options to pass to translator
+	 * @returns {Promise<Object>} Promise resolving to tree object
 	 */
 	generateDependencyTree: async function({cwd = ".", translator="npm", translatorOptions={}} = {}) {
 		// TODO NEXT MAJOR: Rename "translator" option to "translatorName"

lib/projectPreprocessor.js

@@ -496,14 +496,17 @@ class ProjectPreprocessor {
 /**
  * The Project Preprocessor enriches the dependency information with project configuration
  *
- * @module normalizer/translators/static
+ * @public
+ * @namespace
+ * @alias module:@ui5/project.projectPreprocessor
  */
 module.exports = {
 	/**
 	 * Collects project information and its dependencies to enrich it with project configuration
 	 *
+	 * @public
 	 * @param {Object} tree Dependency tree of the project
-	 * @returns {Promise} Promise resolving with the dependency tree and enriched project configuration
+	 * @returns {Promise<Object>} Promise resolving with the dependency tree and enriched project configuration
 	 */
 	processTree: function(tree) {
 		return new ProjectPreprocessor().processTree(tree);

lib/translators/npm.js

@@ -491,16 +491,19 @@ class NpmTranslator {
 /**
  * Translator for npm resources
  *
- * @module normalizer/translators/npm
+ * @private
+ * @namespace
+ * @alias module:@ui5/project.translators.npm
  */
 module.exports = {
 	/**
 	 * Generates a dependency tree for npm projects
 	 *
+	 * @public
 	 * @param {string} dirPath Project path
-	 * @param {object} [options]
+	 * @param {Object} [options]
 	 * @param {boolean} [options.includeDeduped=false]
-	 * @returns {Promise} Promise resolving with a dependency tree
+	 * @returns {Promise<Object>} Promise resolving with a dependency tree
 	 */
 	generateDependencyTree(dirPath, options = {includeDeduped: false}) {
 		return new NpmTranslator(options).generateDependencyTree(dirPath);