From 5fa9b5cd676f5ecb628d85b7ac07b480e1826fd4 Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Tue, 16 Oct 2018 16:56:07 +0200 Subject: [PATCH 1/7] [INTERNAL] JSDoc: Make API private by default Also: - prevent use of unkown tags - add some docdash specific page options --- jsdoc.json | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/jsdoc.json b/jsdoc.json index e08bf7aea..4763d04c9 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -1,6 +1,6 @@ { "tags": { - "allowUnknownTags": true + "allowUnknownTags": false }, "source": { "include": ["README.md"], @@ -13,10 +13,37 @@ "encoding": "utf8", "destination": "jsdocs/", "recurse": true, - "verbose": true + "verbose": true, + "access": "public" }, "templates": { "cleverLinks": false, "monospaceLinks": false + }, + "docdash": { + "sectionOrder": [ + "Modules", + "Classes", + "Externals", + "Events", + "Namespaces", + "Mixins", + "Tutorials", + "Interfaces" + ], + "meta": { + "title": "UI5 Project JSDoc", + "description": "UI5 Build and Development Tooling - UI5 Project", + "keyword": "openui5 sapui5 ui5 build development tool" + }, + "search": true, + "menu": { + "GitHub": { + "href": "https://github.com/SAP/ui5-project", + "target": "_blank", + "class": "menu-item", + "id": "github_link" + } + } } } From 9edb85892167ff9a939bfee929798e793d2cd801 Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Mon, 7 Jan 2019 14:49:29 +0100 Subject: [PATCH 2/7] [INTERNAL] JSDoc: Tag public APIs as @public and fix module names --- lib/normalizer.js | 5 ++++- lib/projectPreprocessor.js | 4 +++- lib/translators/npm.js | 2 +- lib/translators/static.js | 2 +- 4 files changed, 9 insertions(+), 4 deletions(-) diff --git a/lib/normalizer.js b/lib/normalizer.js index a7cf286b4..17cfa0971 100644 --- a/lib/normalizer.js +++ b/lib/normalizer.js @@ -5,12 +5,14 @@ const projectPreprocessor = require("./projectPreprocessor"); /** * Generate project and dependency trees via translators. Optionally configure all projects with the projectPreprocessor. * - * @module normalizer/normalizer + * @public + * @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 @@ -29,6 +31,7 @@ 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 diff --git a/lib/projectPreprocessor.js b/lib/projectPreprocessor.js index 49e6d3f4a..8901f0b1f 100644 --- a/lib/projectPreprocessor.js +++ b/lib/projectPreprocessor.js @@ -496,12 +496,14 @@ class ProjectPreprocessor { /** * The Project Preprocessor enriches the dependency information with project configuration * - * @module normalizer/translators/static + * @public + * @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 */ diff --git a/lib/translators/npm.js b/lib/translators/npm.js index 9ce588cba..3806fcdc3 100644 --- a/lib/translators/npm.js +++ b/lib/translators/npm.js @@ -491,7 +491,7 @@ class NpmTranslator { /** * Translator for npm resources * - * @module normalizer/translators/npm + * @module @ui5/project/translators/npm */ module.exports = { /** diff --git a/lib/translators/static.js b/lib/translators/static.js index 25a9994ee..990547df6 100644 --- a/lib/translators/static.js +++ b/lib/translators/static.js @@ -5,7 +5,7 @@ const parseYaml = require("js-yaml").safeLoad; /** * Translator for static resources * - * @module normalizer/translators/static + * @module @ui5/project/translators/static */ /** From dea042d7bfc7df6ef451efca8bb34b2a691d66c2 Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Mon, 7 Jan 2019 19:17:00 +0100 Subject: [PATCH 3/7] [INTERNAL] ESLint: Replace deprecated valid-jsdoc rule with eslint-plugin-jsdoc As suggested by ESLint: https://eslint.org/blog/2018/11/jsdoc-end-of-life#suggested-replacement --- .eslintrc.js | 36 ++++++++++--- lib/normalizer.js | 2 +- lib/translators/npm.js | 2 +- lib/translators/static.js | 2 +- package-lock.json | 105 ++++++++++++++++++++------------------ package.json | 1 + 6 files changed, 88 insertions(+), 60 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index ae146528b..a710d04b5 100644 --- a/.eslintrc.js +++ b/.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": 2 + }, + "settings": { + "jsdoc": { + "tagNamePreference": { + "return": "returns" } - ], + } }, "root": true }; diff --git a/lib/normalizer.js b/lib/normalizer.js index 17cfa0971..7089fad3a 100644 --- a/lib/normalizer.js +++ b/lib/normalizer.js @@ -35,7 +35,7 @@ const Normalizer = { * @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 + * @param {Object} [options.translatorOptions] Options to pass to translator * @returns {Promise} Promise resolving to tree object */ generateDependencyTree: async function({cwd = ".", translator="npm", translatorOptions={}} = {}) { diff --git a/lib/translators/npm.js b/lib/translators/npm.js index 3806fcdc3..2b219f689 100644 --- a/lib/translators/npm.js +++ b/lib/translators/npm.js @@ -498,7 +498,7 @@ module.exports = { * Generates a dependency tree for npm projects * * @param {string} dirPath Project path - * @param {object} [options] + * @param {Object} [options] * @param {boolean} [options.includeDeduped=false] * @returns {Promise} Promise resolving with a dependency tree */ diff --git a/lib/translators/static.js b/lib/translators/static.js index 990547df6..978359004 100644 --- a/lib/translators/static.js +++ b/lib/translators/static.js @@ -14,7 +14,7 @@ const parseYaml = require("js-yaml").safeLoad; * This feature is EXPERIMENTAL and used for testing purposes only. * * @param {string} dirPath Project path - * @param {object} [options] + * @param {Object} [options] * @param {Array} [options.parameters] CLI configuration options * @returns {Promise} Promise resolving with a dependency tree */ diff --git a/package-lock.json b/package-lock.json index 0d6708058..e950a89cf 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1274,7 +1274,7 @@ "dependencies": { "mkdirp": { "version": "0.5.1", - "resolved": "http://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=", "dev": true, "requires": { @@ -1576,7 +1576,7 @@ }, "mkdirp": { "version": "0.5.1", - "resolved": "http://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=", "dev": true, "requires": { @@ -1894,6 +1894,12 @@ "integrity": "sha1-0bhvkB+LZL2UG96tr5JFMDk76Sg=", "optional": true }, + "comment-parser": { + "version": "0.5.4", + "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-0.5.4.tgz", + "integrity": "sha512-0h7W6Y1Kb6zKQMJqdX41C5qf9ITCVIsD2qP2RaqDF3GFkXFrmuAuv5zUOuo19YzyC9scjBNpqzuaRQ2Sy5pxMQ==", + "dev": true + }, "common-path-prefix": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/common-path-prefix/-/common-path-prefix-1.0.0.tgz", @@ -2542,7 +2548,7 @@ }, "mkdirp": { "version": "0.5.1", - "resolved": "http://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=", "dev": true, "requires": { @@ -2578,6 +2584,25 @@ "integrity": "sha512-z541Fs5TFaY7/35v/z100InQ2f3V2J7e3u/0yKrnImgsHjh6JWgSRngfC/mZepn/+XN16jUydt64k//kxXc1fw==", "dev": true }, + "eslint-plugin-jsdoc": { + "version": "3.15.1", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-3.15.1.tgz", + "integrity": "sha512-xIQ+ajO6M6zsu5XEn5+1QyE1/P1w/l3yAXPCToZjRcrsKsg5yLTsYnrkdoJZJegE70dTZZwQ5bYPCjEbPey6cw==", + "dev": true, + "requires": { + "comment-parser": "^0.5.1", + "jsdoctypeparser": "^2.0.0-alpha-8", + "lodash": "^4.17.11" + }, + "dependencies": { + "lodash": { + "version": "4.17.11", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.11.tgz", + "integrity": "sha512-cQKh8igo5QUhZ7lg38DYWAxMvjSAKG0A8wGSVimP07SIUEK2UO+arSRKbRZWtelMtN5V0Hkwh5ryOto/SshYIg==", + "dev": true + } + } + }, "eslint-scope": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-4.0.0.tgz", @@ -3043,8 +3068,7 @@ "ansi-regex": { "version": "2.1.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "aproba": { "version": "1.2.0", @@ -3065,14 +3089,12 @@ "balanced-match": { "version": "1.0.0", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "brace-expansion": { "version": "1.1.11", "bundled": true, "dev": true, - "optional": true, "requires": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" @@ -3087,20 +3109,17 @@ "code-point-at": { "version": "1.1.0", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "concat-map": { "version": "0.0.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "console-control-strings": { "version": "1.1.0", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "core-util-is": { "version": "1.0.2", @@ -3217,8 +3236,7 @@ "inherits": { "version": "2.0.3", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "ini": { "version": "1.3.5", @@ -3230,7 +3248,6 @@ "version": "1.0.0", "bundled": true, "dev": true, - "optional": true, "requires": { "number-is-nan": "^1.0.0" } @@ -3245,7 +3262,6 @@ "version": "3.0.4", "bundled": true, "dev": true, - "optional": true, "requires": { "brace-expansion": "^1.1.7" } @@ -3253,14 +3269,12 @@ "minimist": { "version": "0.0.8", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "minipass": { "version": "2.2.4", "bundled": true, "dev": true, - "optional": true, "requires": { "safe-buffer": "^5.1.1", "yallist": "^3.0.0" @@ -3279,7 +3293,6 @@ "version": "0.5.1", "bundled": true, "dev": true, - "optional": true, "requires": { "minimist": "0.0.8" } @@ -3360,8 +3373,7 @@ "number-is-nan": { "version": "1.0.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "object-assign": { "version": "4.1.1", @@ -3373,7 +3385,6 @@ "version": "1.4.0", "bundled": true, "dev": true, - "optional": true, "requires": { "wrappy": "1" } @@ -3459,8 +3470,7 @@ "safe-buffer": { "version": "5.1.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "safer-buffer": { "version": "2.1.2", @@ -3496,7 +3506,6 @@ "version": "1.0.2", "bundled": true, "dev": true, - "optional": true, "requires": { "code-point-at": "^1.0.0", "is-fullwidth-code-point": "^1.0.0", @@ -3516,7 +3525,6 @@ "version": "3.0.1", "bundled": true, "dev": true, - "optional": true, "requires": { "ansi-regex": "^2.0.0" } @@ -3560,14 +3568,12 @@ "wrappy": { "version": "1.0.2", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "yallist": { "version": "3.0.2", "bundled": true, - "dev": true, - "optional": true + "dev": true } } }, @@ -4393,7 +4399,7 @@ }, "mkdirp": { "version": "0.5.1", - "resolved": "http://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=", "dev": true, "requires": { @@ -4402,6 +4408,12 @@ } } }, + "jsdoctypeparser": { + "version": "2.0.0-alpha-8", + "resolved": "https://registry.npmjs.org/jsdoctypeparser/-/jsdoctypeparser-2.0.0-alpha-8.tgz", + "integrity": "sha1-uvE3+44qVYgQrc8Z0tKi9oDpCl8=", + "dev": true + }, "jsesc": { "version": "0.5.0", "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-0.5.0.tgz", @@ -4938,7 +4950,7 @@ }, "mkdirp": { "version": "0.3.5", - "resolved": "http://registry.npmjs.org/mkdirp/-/mkdirp-0.3.5.tgz", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.3.5.tgz", "integrity": "sha1-3j5fiWHIjHh+4TaN+EmsRBPsqNc=", "optional": true }, @@ -5110,7 +5122,6 @@ "version": "0.1.4", "bundled": true, "dev": true, - "optional": true, "requires": { "kind-of": "^3.0.2", "longest": "^1.0.1", @@ -5435,8 +5446,7 @@ "is-buffer": { "version": "1.1.6", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "is-builtin-module": { "version": "1.0.0", @@ -5520,7 +5530,6 @@ "version": "3.2.2", "bundled": true, "dev": true, - "optional": true, "requires": { "is-buffer": "^1.1.5" } @@ -5567,8 +5576,7 @@ "longest": { "version": "1.0.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "lru-cache": { "version": "4.1.3", @@ -5834,8 +5842,7 @@ "repeat-string": { "version": "1.6.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "require-directory": { "version": "2.1.1", @@ -6947,7 +6954,7 @@ }, "require-uncached": { "version": "1.0.3", - "resolved": "http://registry.npmjs.org/require-uncached/-/require-uncached-1.0.3.tgz", + "resolved": "https://registry.npmjs.org/require-uncached/-/require-uncached-1.0.3.tgz", "integrity": "sha1-Tg1W1slmL9MeQwEcS5WqSZVUIdM=", "dev": true, "requires": { @@ -7057,7 +7064,7 @@ }, "safe-regex": { "version": "1.1.0", - "resolved": "http://registry.npmjs.org/safe-regex/-/safe-regex-1.1.0.tgz", + "resolved": "https://registry.npmjs.org/safe-regex/-/safe-regex-1.1.0.tgz", "integrity": "sha1-QKNmnzsHfR6UPURinhV91IAjvy4=", "requires": { "ret": "~0.1.10" @@ -7729,7 +7736,7 @@ }, "through": { "version": "2.3.8", - "resolved": "http://registry.npmjs.org/through/-/through-2.3.8.tgz", + "resolved": "https://registry.npmjs.org/through/-/through-2.3.8.tgz", "integrity": "sha1-DdTJ/6q8NXlgsbckEV1+Doai4fU=", "dev": true }, @@ -7972,7 +7979,7 @@ "dependencies": { "mkdirp": { "version": "0.5.1", - "resolved": "http://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=", "dev": true, "requires": { @@ -8192,7 +8199,7 @@ "dependencies": { "mkdirp": { "version": "0.5.1", - "resolved": "http://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.1.tgz", "integrity": "sha1-MAV0OOrGz3+MR2fzhkjWaX11yQM=", "dev": true, "requires": { @@ -8261,7 +8268,7 @@ }, "xmlbuilder": { "version": "9.0.7", - "resolved": "http://registry.npmjs.org/xmlbuilder/-/xmlbuilder-9.0.7.tgz", + "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-9.0.7.tgz", "integrity": "sha1-Ey7mPS7FVlxVfiD0wi35rKaGsQ0=" }, "xmlcreate": { diff --git a/package.json b/package.json index 23d6f4dac..64e50196f 100644 --- a/package.json +++ b/package.json @@ -108,6 +108,7 @@ "docdash": "^1.0.2", "eslint": "^5.11.1", "eslint-config-google": "^0.11.0", + "eslint-plugin-jsdoc": "^3.15.1", "jsdoc": "^3.5.5", "nyc": "^13.1.0", "sinon": "^7.2.2", From 2e9db485b72a552a00a66e602ac2e7d5ee2e445c Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Mon, 7 Jan 2019 19:24:09 +0100 Subject: [PATCH 4/7] [INTERNAL] JSDoc: Set wrap option and add openGraph meta data Wrapping navigation names is necessary because our module names are very long. --- jsdoc.json | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/jsdoc.json b/jsdoc.json index 4763d04c9..6f74fcc73 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -20,6 +20,13 @@ "cleverLinks": false, "monospaceLinks": false }, + "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", @@ -32,11 +39,12 @@ "Interfaces" ], "meta": { - "title": "UI5 Project JSDoc", - "description": "UI5 Build and Development Tooling - UI5 Project", - "keyword": "openui5 sapui5 ui5 build development tool" + "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", From f4241b904263424fda1635e10e24bf39c6255476 Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Tue, 8 Jan 2019 18:54:55 +0100 Subject: [PATCH 5/7] [INTERNAL] package.json: Add missing opn-cli module Required for jsdoc script. All other UI5 Toolign modules already have it --- package-lock.json | 177 ++++++++++++++++++++++++++++++++++++++++++++++ package.json | 1 + 2 files changed, 178 insertions(+) diff --git a/package-lock.json b/package-lock.json index e950a89cf..c7f4e9583 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2145,6 +2145,16 @@ "integrity": "sha1-9lNNFRSCabIDUue+4m9QH5oZEpA=", "dev": true }, + "decamelize-keys": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/decamelize-keys/-/decamelize-keys-1.1.0.tgz", + "integrity": "sha1-0XGoeTMlKAfrPLYdwcFEXQeN8tk=", + "dev": true, + "requires": { + "decamelize": "^1.1.0", + "map-obj": "^1.0.0" + } + }, "decode-uri-component": { "version": "0.2.0", "resolved": "https://registry.npmjs.org/decode-uri-component/-/decode-uri-component-0.2.0.tgz", @@ -2941,6 +2951,12 @@ "object-assign": "^4.0.1" } }, + "file-type": { + "version": "10.7.0", + "resolved": "https://registry.npmjs.org/file-type/-/file-type-10.7.0.tgz", + "integrity": "sha512-AbaGtdWYYRaVrv2MwL/65myuRJ9j3e79e7etJ79US18QHuVlzJBcQHUH+HxDUoLtbyWRTUfLzLkGXX3pP9kfZg==", + "dev": true + }, "filename-regex": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/filename-regex/-/filename-regex-2.0.1.tgz", @@ -4286,6 +4302,12 @@ "resolved": "https://registry.npmjs.org/is-windows/-/is-windows-1.0.2.tgz", "integrity": "sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA==" }, + "is-wsl": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-1.1.0.tgz", + "integrity": "sha1-HxbkqiKwTRM2tmGIpmrzxgDDpm0=", + "dev": true + }, "isarray": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz", @@ -4929,6 +4951,16 @@ "integrity": "sha1-hX/Kv8M5fSYluCKCYuhqp6ARsF0=", "dev": true }, + "minimist-options": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/minimist-options/-/minimist-options-3.0.2.tgz", + "integrity": "sha512-FyBrT/d0d4+uiZRbqznPXqw3IpZZG3gl3wKWiX784FycUKVwBt0uLBFkQrtE4tZOrgo78nZp2jnKz3L65T5LdQ==", + "dev": true, + "requires": { + "arrify": "^1.0.1", + "is-plain-obj": "^1.1.0" + } + }, "mixin-deep": { "version": "1.3.1", "resolved": "https://registry.npmjs.org/mixin-deep/-/mixin-deep-1.3.1.tgz", @@ -6334,6 +6366,108 @@ "mimic-fn": "^1.0.0" } }, + "opn": { + "version": "5.4.0", + "resolved": "https://registry.npmjs.org/opn/-/opn-5.4.0.tgz", + "integrity": "sha512-YF9MNdVy/0qvJvDtunAOzFw9iasOQHpVthTCvGzxt61Il64AYSGdK+rYwld7NAfk9qJ7dt+hymBNSc9LNYS+Sw==", + "dev": true, + "requires": { + "is-wsl": "^1.1.0" + } + }, + "opn-cli": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/opn-cli/-/opn-cli-4.0.0.tgz", + "integrity": "sha512-/NxjgPPxgYWAEznUwbvQd3H/vfMBRoIy8ZAvKNNgye2TbFE4pToVwmbi34Xo2rkmlfJIeWPa++zUSj4WBVGJxQ==", + "dev": true, + "requires": { + "file-type": "^10.4.0", + "get-stdin": "^6.0.0", + "meow": "^5.0.0", + "opn": "^5.4.0", + "temp-write": "^3.4.0" + }, + "dependencies": { + "camelcase": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-4.1.0.tgz", + "integrity": "sha1-1UVjW+HjPFQmScaRc+Xeas+uNN0=", + "dev": true + }, + "camelcase-keys": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/camelcase-keys/-/camelcase-keys-4.2.0.tgz", + "integrity": "sha1-oqpfsa9oh1glnDLBQUJteJI7m3c=", + "dev": true, + "requires": { + "camelcase": "^4.1.0", + "map-obj": "^2.0.0", + "quick-lru": "^1.0.0" + } + }, + "get-stdin": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/get-stdin/-/get-stdin-6.0.0.tgz", + "integrity": "sha512-jp4tHawyV7+fkkSKyvjuLZswblUtz+SQKzSWnBbii16BuZksJlU1wuBYXY75r+duh/llF1ur6oNwi+2ZzjKZ7g==", + "dev": true + }, + "map-obj": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/map-obj/-/map-obj-2.0.0.tgz", + "integrity": "sha1-plzSkIepJZi4eRJXpSPgISIqwfk=", + "dev": true + }, + "meow": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/meow/-/meow-5.0.0.tgz", + "integrity": "sha512-CbTqYU17ABaLefO8vCU153ZZlprKYWDljcndKKDCFcYQITzWCXZAVk4QMFZPgvzrnUQ3uItnIE/LoUOwrT15Ig==", + "dev": true, + "requires": { + "camelcase-keys": "^4.0.0", + "decamelize-keys": "^1.0.0", + "loud-rejection": "^1.0.0", + "minimist-options": "^3.0.1", + "normalize-package-data": "^2.3.4", + "read-pkg-up": "^3.0.0", + "redent": "^2.0.0", + "trim-newlines": "^2.0.0", + "yargs-parser": "^10.0.0" + } + }, + "read-pkg-up": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/read-pkg-up/-/read-pkg-up-3.0.0.tgz", + "integrity": "sha1-PtSWaF26D4/hGNBpHcUfSh/5bwc=", + "dev": true, + "requires": { + "find-up": "^2.0.0", + "read-pkg": "^3.0.0" + } + }, + "redent": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/redent/-/redent-2.0.0.tgz", + "integrity": "sha1-wbIAe0LVfrE4kHmzyDM2OdXhzKo=", + "dev": true, + "requires": { + "indent-string": "^3.0.0", + "strip-indent": "^2.0.0" + } + }, + "strip-indent": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-2.0.0.tgz", + "integrity": "sha1-XvjbKV0B5u1sv3qrlpmNeCJSe2g=", + "dev": true + }, + "trim-newlines": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/trim-newlines/-/trim-newlines-2.0.0.tgz", + "integrity": "sha1-tAPQuRvlDDMd/EuC7s6yLD3hbSA=", + "dev": true + } + } + }, "option-chain": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/option-chain/-/option-chain-1.0.0.tgz", @@ -6644,6 +6778,12 @@ "resolved": "https://registry.npmjs.org/qs/-/qs-6.5.2.tgz", "integrity": "sha512-N5ZAX4/LxJmF+7wN74pUD6qAh9/wnvdQcjq9TZjevvXzSUo7bfmw91saqMjzGS2xq91/odN2dW/WOl7qQHNDGA==" }, + "quick-lru": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/quick-lru/-/quick-lru-1.1.0.tgz", + "integrity": "sha1-Q2CxfGETatOAeDl/8RQW4Ybc+7g=", + "dev": true + }, "random-int": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/random-int/-/random-int-1.0.0.tgz", @@ -7713,6 +7853,26 @@ "readable-stream": "^2" } }, + "temp-dir": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/temp-dir/-/temp-dir-1.0.0.tgz", + "integrity": "sha1-CnwOom06Oa+n4OvqnB/AvE2qAR0=", + "dev": true + }, + "temp-write": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/temp-write/-/temp-write-3.4.0.tgz", + "integrity": "sha1-jP9jD7fp2gXwR8dM5M5NaFRX1JI=", + "dev": true, + "requires": { + "graceful-fs": "^4.1.2", + "is-stream": "^1.1.0", + "make-dir": "^1.0.0", + "pify": "^3.0.0", + "temp-dir": "^1.0.0", + "uuid": "^3.0.1" + } + }, "term-size": { "version": "1.2.0", "resolved": "https://registry.npmjs.org/term-size/-/term-size-1.2.0.tgz", @@ -8289,6 +8449,23 @@ "integrity": "sha1-HBH5IY8HYImkfdUS+TxmmaaoHVI=", "dev": true }, + "yargs-parser": { + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-10.1.0.tgz", + "integrity": "sha512-VCIyR1wJoEBZUqk5PA+oOBF6ypbwh5aNB3I50guxAL/quggdfs4TtNHQrSazFA3fYZ+tEqfs0zIGlv0c/rgjbQ==", + "dev": true, + "requires": { + "camelcase": "^4.1.0" + }, + "dependencies": { + "camelcase": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-4.1.0.tgz", + "integrity": "sha1-1UVjW+HjPFQmScaRc+Xeas+uNN0=", + "dev": true + } + } + }, "yazl": { "version": "2.5.1", "resolved": "https://registry.npmjs.org/yazl/-/yazl-2.5.1.tgz", diff --git a/package.json b/package.json index 64e50196f..c539388d7 100644 --- a/package.json +++ b/package.json @@ -111,6 +111,7 @@ "eslint-plugin-jsdoc": "^3.15.1", "jsdoc": "^3.5.5", "nyc": "^13.1.0", + "opn-cli": "^4.0.0", "sinon": "^7.2.2", "tap-nyan": "^1.1.0" } From af5274f22227e97fce772e2d623a3509340a8610 Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Tue, 8 Jan 2019 18:55:33 +0100 Subject: [PATCH 6/7] [INTERNAL] JSDoc: Restructure modules via namespaces --- index.js | 16 +++++++++++++--- jsdoc.json | 9 ++++++--- lib/normalizer.js | 8 ++++---- lib/projectPreprocessor.js | 3 ++- lib/translators/npm.js | 2 +- lib/translators/static.js | 2 +- 6 files changed, 27 insertions(+), 13 deletions(-) diff --git a/index.js b/index.js index 82986dfb7..0d6fd4b7b 100644 --- a/index.js +++ b/index.js @@ -1,10 +1,20 @@ -const ui5Project = { +/** + * @module @ui5/project + * @public + */ +module.exports = { + /** + * @public + * @see @ui5/project.normalizer + */ normalizer: require("./lib/normalizer"), + /** + * @public + * @see @ui5/project.projectPreprocessor + */ projectPreprocessor: require("./lib/projectPreprocessor"), translators: { "npm": require("./lib/translators/npm"), "static": require("./lib/translators/static") } }; - -module.exports = ui5Project; diff --git a/jsdoc.json b/jsdoc.json index 6f74fcc73..0a9afb11b 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -3,7 +3,7 @@ "allowUnknownTags": false }, "source": { - "include": ["README.md"], + "include": ["README.md", "index.js"], "includePattern": ".+\\.js$", "excludePattern": "(node_modules(\\\\|/))" }, @@ -18,7 +18,10 @@ }, "templates": { "cleverLinks": false, - "monospaceLinks": false + "monospaceLinks": false, + "default": { + "useLongnameInNav": true + } }, "openGraph": { "title": "UI5 Build and Development Tooling - API Reference", @@ -30,10 +33,10 @@ "docdash": { "sectionOrder": [ "Modules", + "Namespaces", "Classes", "Externals", "Events", - "Namespaces", "Mixins", "Tutorials", "Interfaces" diff --git a/lib/normalizer.js b/lib/normalizer.js index 7089fad3a..e8b394001 100644 --- a/lib/normalizer.js +++ b/lib/normalizer.js @@ -6,13 +6,14 @@ const projectPreprocessor = require("./projectPreprocessor"); * Generate project and dependency trees via translators. Optionally configure all projects with the projectPreprocessor. * * @public - * @module @ui5/project/normalizer + * @namespace @ui5/project.normalizer */ -const Normalizer = { +const Normalizer = module.exports = { /** * Generates a project and dependency tree via translators and configures all projects via the projectPreprocessor * * @public + * @memberof @ui5/project.normalizer * @param {Object} [options] * @param {string} [options.cwd] Current working directory * @param {string} [options.configPath] Path to configuration file @@ -32,6 +33,7 @@ const Normalizer = { * Generates a project and dependency tree via translators * * @public + * @memberof @ui5/project.normalizer * @param {Object} [options] * @param {string} [options.cwd=.] Current working directory * @param {string} [options.translator=npm] Translator to use @@ -66,5 +68,3 @@ const Normalizer = { return translatorModule.generateDependencyTree(cwd, translatorOptions); } }; - -module.exports = Normalizer; diff --git a/lib/projectPreprocessor.js b/lib/projectPreprocessor.js index 8901f0b1f..4cd1ae4b9 100644 --- a/lib/projectPreprocessor.js +++ b/lib/projectPreprocessor.js @@ -497,13 +497,14 @@ class ProjectPreprocessor { * The Project Preprocessor enriches the dependency information with project configuration * * @public - * @module @ui5/project/projectPreprocessor + * @namespace @ui5/project.projectPreprocessor */ module.exports = { /** * Collects project information and its dependencies to enrich it with project configuration * * @public + * @memberof @ui5/project.projectPreprocessor * @param {Object} tree Dependency tree of the project * @returns {Promise} Promise resolving with the dependency tree and enriched project configuration */ diff --git a/lib/translators/npm.js b/lib/translators/npm.js index 2b219f689..fd1b4ee99 100644 --- a/lib/translators/npm.js +++ b/lib/translators/npm.js @@ -491,7 +491,7 @@ class NpmTranslator { /** * Translator for npm resources * - * @module @ui5/project/translators/npm + * @alias @ui5/project.translators/npm */ module.exports = { /** diff --git a/lib/translators/static.js b/lib/translators/static.js index 978359004..a893f7e68 100644 --- a/lib/translators/static.js +++ b/lib/translators/static.js @@ -5,7 +5,7 @@ const parseYaml = require("js-yaml").safeLoad; /** * Translator for static resources * - * @module @ui5/project/translators/static + * @alias @ui5/project.translators/static */ /** From 48b06e248ae68e704da9321b95ca16a289770439 Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Wed, 9 Jan 2019 15:44:31 +0100 Subject: [PATCH 7/7] [INTERNAL] JSDoc: Refactor to use module: syntax and fix various docs --- .eslintrc.js | 2 +- docs/BuildExtensibility.md | 78 +++++++++++++++++++------------------- index.js | 13 +++---- lib/normalizer.js | 16 ++++---- lib/projectPreprocessor.js | 6 +-- lib/translators/npm.js | 7 +++- lib/translators/static.js | 62 +++++++++++++++--------------- 7 files changed, 94 insertions(+), 90 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index a710d04b5..c456b2910 100644 --- a/.eslintrc.js +++ b/.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": { diff --git a/docs/BuildExtensibility.md b/docs/BuildExtensibility.md index cf8b6edb8..b4542495b 100644 --- a/docs/BuildExtensibility.md +++ b/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} 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); + })); + }); }; -```` \ No newline at end of file +```` diff --git a/index.js b/index.js index 0d6fd4b7b..a80314ee5 100644 --- a/index.js +++ b/index.js @@ -1,18 +1,15 @@ /** - * @module @ui5/project + * @module module:@ui5/project * @public */ module.exports = { - /** - * @public - * @see @ui5/project.normalizer - */ normalizer: require("./lib/normalizer"), + projectPreprocessor: require("./lib/projectPreprocessor"), /** - * @public - * @see @ui5/project.projectPreprocessor + * @private + * @see module:@ui5/project.translators + * @namespace */ - projectPreprocessor: require("./lib/projectPreprocessor"), translators: { "npm": require("./lib/translators/npm"), "static": require("./lib/translators/static") diff --git a/lib/normalizer.js b/lib/normalizer.js index e8b394001..7adce26a9 100644 --- a/lib/normalizer.js +++ b/lib/normalizer.js @@ -3,22 +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. * * @public - * @namespace @ui5/project.normalizer + * @namespace + * @alias module:@ui5/project.normalizer */ -const Normalizer = module.exports = { +const Normalizer = { /** * Generates a project and dependency tree via translators and configures all projects via the projectPreprocessor * * @public - * @memberof @ui5/project.normalizer * @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} Promise resolving to tree object */ generateProjectTree: async function(options = {}) { const tree = await Normalizer.generateDependencyTree(options); @@ -33,12 +34,11 @@ const Normalizer = module.exports = { * Generates a project and dependency tree via translators * * @public - * @memberof @ui5/project.normalizer * @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 + * @returns {Promise} Promise resolving to tree object */ generateDependencyTree: async function({cwd = ".", translator="npm", translatorOptions={}} = {}) { // TODO NEXT MAJOR: Rename "translator" option to "translatorName" @@ -68,3 +68,5 @@ const Normalizer = module.exports = { return translatorModule.generateDependencyTree(cwd, translatorOptions); } }; + +module.exports = Normalizer; diff --git a/lib/projectPreprocessor.js b/lib/projectPreprocessor.js index 4cd1ae4b9..7ceca20ec 100644 --- a/lib/projectPreprocessor.js +++ b/lib/projectPreprocessor.js @@ -497,16 +497,16 @@ class ProjectPreprocessor { * The Project Preprocessor enriches the dependency information with project configuration * * @public - * @namespace @ui5/project.projectPreprocessor + * @namespace + * @alias module:@ui5/project.projectPreprocessor */ module.exports = { /** * Collects project information and its dependencies to enrich it with project configuration * * @public - * @memberof @ui5/project.projectPreprocessor * @param {Object} tree Dependency tree of the project - * @returns {Promise} Promise resolving with the dependency tree and enriched project configuration + * @returns {Promise} Promise resolving with the dependency tree and enriched project configuration */ processTree: function(tree) { return new ProjectPreprocessor().processTree(tree); diff --git a/lib/translators/npm.js b/lib/translators/npm.js index fd1b4ee99..d360bc875 100644 --- a/lib/translators/npm.js +++ b/lib/translators/npm.js @@ -491,16 +491,19 @@ class NpmTranslator { /** * Translator for npm resources * - * @alias @ui5/project.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 {boolean} [options.includeDeduped=false] - * @returns {Promise} Promise resolving with a dependency tree + * @returns {Promise} Promise resolving with a dependency tree */ generateDependencyTree(dirPath, options = {includeDeduped: false}) { return new NpmTranslator(options).generateDependencyTree(dirPath); diff --git a/lib/translators/static.js b/lib/translators/static.js index a893f7e68..7f640cdca 100644 --- a/lib/translators/static.js +++ b/lib/translators/static.js @@ -5,37 +5,39 @@ const parseYaml = require("js-yaml").safeLoad; /** * Translator for static resources * - * @alias @ui5/project.translators/static + * @private + * @namespace + * @alias module:@ui5/project.translators.static */ +module.exports = { + /** + * Generates a dependency tree from static resources + * + * This feature is EXPERIMENTAL and used for testing purposes only. + * + * @public + * @param {string} dirPath Project path + * @param {Object} [options] + * @param {Array} [options.parameters] CLI configuration options + * @returns {Promise} Promise resolving with a dependency tree + */ + generateDependencyTree(dirPath, options = {}) { + // TODO NEXT MAJOR: "options" used to be the the parameters array. We check for that here to stay compatible: + const parameters = Array.isArray(options) ? options : options.parameters; + const depFilePath = parameters && parameters[0] || path.join(dirPath, "projectDependencies.yaml"); -/** - * Generates a dependency tree from static resources - * - * This feature is EXPERIMENTAL and used for testing purposes only. - * - * @param {string} dirPath Project path - * @param {Object} [options] - * @param {Array} [options.parameters] CLI configuration options - * @returns {Promise} Promise resolving with a dependency tree - */ -function generateDependencyTree(dirPath, options = {}) { - // TODO NEXT MAJOR: "options" used to be the the parameters array. We check for that here to stay compatible: - const parameters = Array.isArray(options) ? options : options.parameters; - const depFilePath = parameters && parameters[0] || path.join(dirPath, "projectDependencies.yaml"); - - return new Promise(function(resolve, reject) { - fs.readFile(depFilePath, function(err, buffer) { - if (err) { - reject(new Error(`[static translator] Failed to locate projectDependencies.json at path: "${dirPath}" - Error: ${err.message}`)); - } else { - resolve(parseYaml(buffer.toString(), { - filename: depFilePath - })); - } + return new Promise(function(resolve, reject) { + fs.readFile(depFilePath, function(err, buffer) { + if (err) { + reject(new Error( + `[static translator] Failed to locate projectDependencies.json at path: "${dirPath}" `+ + `- Error: ${err.message}`)); + } else { + resolve(parseYaml(buffer.toString(), { + filename: depFilePath + })); + } + }); }); - }); -} - -module.exports = { - generateDependencyTree: generateDependencyTree + } };