From 0f44ef85287ad5bd41e3af96a2ee84b1f61142ce Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Tue, 16 Oct 2018 16:56:07 +0200 Subject: [PATCH 1/6] [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 e08bf7ae..01e7dee0 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 Server JSDoc", + "description": "UI5 Build and Development Tooling - UI5 Server", + "keyword": "openui5 sapui5 ui5 build development tool" + }, + "search": true, + "menu": { + "GitHub": { + "href": "https://github.com/SAP/ui5-server", + "target": "_blank", + "class": "menu-item", + "id": "github_link" + } + } } } From 7f60bb8d61ef163e91da260e71133ea557e9f80b Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Mon, 7 Jan 2019 14:49:29 +0100 Subject: [PATCH 2/6] [INTERNAL] JSDoc: Tag public APIs as @public and fix module names --- lib/middleware/discovery.js | 2 +- lib/middleware/nonReadRequests.js | 2 +- lib/middleware/serveIndex.js | 2 +- lib/middleware/serveResources.js | 2 +- lib/middleware/serveThemes.js | 2 +- lib/middleware/versionInfo.js | 2 +- lib/server.js | 3 ++- lib/sslUtil.js | 2 +- 8 files changed, 9 insertions(+), 8 deletions(-) diff --git a/lib/middleware/discovery.js b/lib/middleware/discovery.js index 8ed0a392..9a50debd 100644 --- a/lib/middleware/discovery.js +++ b/lib/middleware/discovery.js @@ -12,7 +12,7 @@ const urlPattern = /\/(app_pages|all_libs|all_tests)(?:[?#].*)?$/; *
  • /discovery/all_tests: list all tests
    • * * - * @module server/middleware/discovery + * @module @ui5/server/middleware/discovery * @param {Object} resourceCollections Contains the resource reader or collection to access project related files * @param {AbstractReader} resourceCollections.source Resource reader or collection for the source project * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies diff --git a/lib/middleware/nonReadRequests.js b/lib/middleware/nonReadRequests.js index 5da2d797..70c91e11 100644 --- a/lib/middleware/nonReadRequests.js +++ b/lib/middleware/nonReadRequests.js @@ -4,7 +4,7 @@ * Handles non read requests (POST, PUT, DELETE...) and returns an error 404, * because those operations aren't supported by the server. * - * @module server/middleware/nonReadRequests + * @module @ui5/server/middleware/nonReadRequests * @returns {function} Returns a server middleware closure. */ function createMiddleware() { diff --git a/lib/middleware/serveIndex.js b/lib/middleware/serveIndex.js index 8ed9b017..22d76107 100644 --- a/lib/middleware/serveIndex.js +++ b/lib/middleware/serveIndex.js @@ -131,7 +131,7 @@ function createContent(path, resourceInfos) { /** * Creates and returns the middleware to serve a resource index. * - * @module server/middleware/serveIndex + * @module @ui5/server/middleware/serveIndex * @param {Object} resourceCollections Contains the resource reader or collection to access project related files * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies * @returns {function} Returns a server middleware closure. diff --git a/lib/middleware/serveResources.js b/lib/middleware/serveResources.js index d80010c6..81f0db33 100644 --- a/lib/middleware/serveResources.js +++ b/lib/middleware/serveResources.js @@ -17,7 +17,7 @@ function isFresh(req, res) { /** * Creates and returns the middleware to serve application resources. * - * @module server/middleware/serveResources + * @module @ui5/server/middleware/serveResources * @param {Object} resourceCollections Contains the resource reader or collection to access project related files * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies * @returns {function} Returns a server middleware closure. diff --git a/lib/middleware/serveThemes.js b/lib/middleware/serveThemes.js index 4da17d10..081f2950 100644 --- a/lib/middleware/serveThemes.js +++ b/lib/middleware/serveThemes.js @@ -16,7 +16,7 @@ const themeRequest = /^(.*\/)library(?:(\.css)|(-RTL\.css)|(-parameters\.json))$ * * The theme is built in realtime. If a less file was modified, the theme build is triggered to rebuild the theme. * - * @module server/middleware/serveThemes + * @module @ui5/server/middleware/serveThemes * @param {Object} resourceCollections Contains the resource reader or collection to access project related files * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies * @returns {function} Returns a server middleware closure. diff --git a/lib/middleware/versionInfo.js b/lib/middleware/versionInfo.js index c9e30687..553e6566 100644 --- a/lib/middleware/versionInfo.js +++ b/lib/middleware/versionInfo.js @@ -3,7 +3,7 @@ const createVersionInfoProcessor = require("@ui5/builder").processors.versionInf /** * Creates and returns the middleware to create the version info as json object. * - * @module server/middleware/versionInfo + * @module @ui5/server/middleware/versionInfo * @param {Object} resourceCollections Contains the resource reader or collection to access project related files * @param {AbstractReader} resourceCollections.dependencies Resource collection which contains the project dependencies * @returns {function} Returns a server middleware closure. diff --git a/lib/server.js b/lib/server.js index 4f87a227..85108fd1 100644 --- a/lib/server.js +++ b/lib/server.js @@ -18,7 +18,8 @@ const ReaderCollectionPrioritized = ui5Fs.ReaderCollectionPrioritized; /** * Start a server for the given project (sub-)tree * - * @module server/server + * @public + * @module @ui5/server/server * @param {Object} tree A (sub-)tree * @param {Object} options Options * @param {number} options.port Port to listen to diff --git a/lib/sslUtil.js b/lib/sslUtil.js index ff54442d..37dfd951 100644 --- a/lib/sslUtil.js +++ b/lib/sslUtil.js @@ -16,7 +16,7 @@ const sslUtil = { /** * Creates a new SSL certificate or validates an existing one. * - * @module server/sslUtil + * @module @ui5/server/sslUtil * @param {string} [keyPath=$HOME/.ui5/server/server.key] Path to private key to be used for https. * Defaults to $HOME/.ui5/server/server.key * @param {string} [certPath=$HOME/.ui5/server/server.crt] Path to certificate to be used for for https. From cc8a4263f5282a354efaebd18f656ecb18224e28 Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Mon, 7 Jan 2019 19:17:58 +0100 Subject: [PATCH 3/6] [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/middleware/discovery.js | 2 +- lib/middleware/nonReadRequests.js | 2 +- lib/middleware/serveIndex.js | 12 ++--- lib/middleware/serveResources.js | 2 +- lib/middleware/serveThemes.js | 2 +- lib/middleware/versionInfo.js | 2 +- lib/server.js | 7 +-- lib/sslUtil.js | 2 +- package-lock.json | 83 +++++++++++++++++-------------- package.json | 1 + 11 files changed, 90 insertions(+), 61 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index ae146528..a710d04b 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/middleware/discovery.js b/lib/middleware/discovery.js index 9a50debd..054887a7 100644 --- a/lib/middleware/discovery.js +++ b/lib/middleware/discovery.js @@ -16,7 +16,7 @@ const urlPattern = /\/(app_pages|all_libs|all_tests)(?:[?#].*)?$/; * @param {Object} resourceCollections Contains the resource reader or collection to access project related files * @param {AbstractReader} resourceCollections.source Resource reader or collection for the source project * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies - * @returns {function} Returns a server middleware closure. + * @returns {Function} Returns a server middleware closure. */ function createMiddleware({resourceCollections}) { return function discoveryMiddleware(req, res, next) { diff --git a/lib/middleware/nonReadRequests.js b/lib/middleware/nonReadRequests.js index 70c91e11..f6fc685f 100644 --- a/lib/middleware/nonReadRequests.js +++ b/lib/middleware/nonReadRequests.js @@ -5,7 +5,7 @@ * because those operations aren't supported by the server. * * @module @ui5/server/middleware/nonReadRequests - * @returns {function} Returns a server middleware closure. + * @returns {Function} Returns a server middleware closure. */ function createMiddleware() { return function nonReadRequests(req, res, next) { diff --git a/lib/middleware/serveIndex.js b/lib/middleware/serveIndex.js index 22d76107..fa747d32 100644 --- a/lib/middleware/serveIndex.js +++ b/lib/middleware/serveIndex.js @@ -11,7 +11,7 @@ const GB = KB * KB * KB; * Returns the mime type of the given resource * * @param {Resource} resource the resource - * @returns {String} mime type + * @returns {string} mime type */ function getMimeType(resource) { if (rProperties.test(resource.getPath())) { @@ -24,8 +24,8 @@ function getMimeType(resource) { /** * Converts the given bytes into a proper human readable size * - * @param {Number} bytes bytes - * @returns {String} human readable size + * @param {number} bytes bytes + * @returns {string} human readable size */ function formatSize(bytes) { let result; @@ -90,9 +90,9 @@ function createResourceInfos(resources) { /** * Creates the HTML content for the resource listing * - * @param {String} path the path + * @param {string} path the path * @param {Object[]} resourceInfos an array of resource infos - * @returns {String} HTML content for the resource listing + * @returns {string} HTML content for the resource listing */ function createContent(path, resourceInfos) { return ` @@ -134,7 +134,7 @@ function createContent(path, resourceInfos) { * @module @ui5/server/middleware/serveIndex * @param {Object} resourceCollections Contains the resource reader or collection to access project related files * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies - * @returns {function} Returns a server middleware closure. + * @returns {Function} Returns a server middleware closure. */ function createMiddleware({resourceCollections}) { return function serveIndex(req, res, next) { diff --git a/lib/middleware/serveResources.js b/lib/middleware/serveResources.js index 81f0db33..eb9755fc 100644 --- a/lib/middleware/serveResources.js +++ b/lib/middleware/serveResources.js @@ -20,7 +20,7 @@ function isFresh(req, res) { * @module @ui5/server/middleware/serveResources * @param {Object} resourceCollections Contains the resource reader or collection to access project related files * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies - * @returns {function} Returns a server middleware closure. + * @returns {Function} Returns a server middleware closure. */ function createMiddleware({resourceCollections}) { return function serveResources(req, res, next) { diff --git a/lib/middleware/serveThemes.js b/lib/middleware/serveThemes.js index 081f2950..b2649f91 100644 --- a/lib/middleware/serveThemes.js +++ b/lib/middleware/serveThemes.js @@ -19,7 +19,7 @@ const themeRequest = /^(.*\/)library(?:(\.css)|(-RTL\.css)|(-parameters\.json))$ * @module @ui5/server/middleware/serveThemes * @param {Object} resourceCollections Contains the resource reader or collection to access project related files * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies - * @returns {function} Returns a server middleware closure. + * @returns {Function} Returns a server middleware closure. */ function createMiddleware({resourceCollections}) { const builder = new themeBuilder.ThemeBuilder({ diff --git a/lib/middleware/versionInfo.js b/lib/middleware/versionInfo.js index 553e6566..d94c94a9 100644 --- a/lib/middleware/versionInfo.js +++ b/lib/middleware/versionInfo.js @@ -6,7 +6,7 @@ const createVersionInfoProcessor = require("@ui5/builder").processors.versionInf * @module @ui5/server/middleware/versionInfo * @param {Object} resourceCollections Contains the resource reader or collection to access project related files * @param {AbstractReader} resourceCollections.dependencies Resource collection which contains the project dependencies - * @returns {function} Returns a server middleware closure. + * @returns {Function} Returns a server middleware closure. */ function createMiddleware({resourceCollections, tree: project}) { return function versionInfo(req, res, next) { diff --git a/lib/server.js b/lib/server.js index 85108fd1..f5fe0fa8 100644 --- a/lib/server.js +++ b/lib/server.js @@ -171,9 +171,10 @@ function _listen(app, port, changePortIfInUse, acceptRemoteConnections) { /** * Adds SSL support to an express application * - * @param {Object} app The original express application - * @param {string} key Path to private key to be used for https - * @param {string} cert Path to certificate to be used for for https + * @param {Object} parameters + * @param {Object} parameters.app The original express application + * @param {string} parameters.key Path to private key to be used for https + * @param {string} parameters.cert Path to certificate to be used for for https * @returns {Object} The express application with SSL support * @private */ diff --git a/lib/sslUtil.js b/lib/sslUtil.js index 37dfd951..08adf31d 100644 --- a/lib/sslUtil.js +++ b/lib/sslUtil.js @@ -21,7 +21,7 @@ const sslUtil = { * Defaults to $HOME/.ui5/server/server.key * @param {string} [certPath=$HOME/.ui5/server/server.crt] Path to certificate to be used for for https. * Defaults to $HOME/.ui5/server/server.crt - * @returns {Promise} Resolves with an sslObject containing cert and key + * @returns {Promise} Resolves with an sslObject containing cert and key */ getSslCertificate: function( keyPath = path.join(os.homedir(), ".ui5/server/server.key"), diff --git a/package-lock.json b/package-lock.json index 19d772dc..73f8a768 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1982,6 +1982,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", @@ -2824,6 +2830,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", @@ -3406,8 +3431,7 @@ "ansi-regex": { "version": "2.1.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "aproba": { "version": "1.2.0", @@ -3428,14 +3452,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" @@ -3450,20 +3472,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", @@ -3580,8 +3599,7 @@ "inherits": { "version": "2.0.3", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "ini": { "version": "1.3.5", @@ -3593,7 +3611,6 @@ "version": "1.0.0", "bundled": true, "dev": true, - "optional": true, "requires": { "number-is-nan": "^1.0.0" } @@ -3608,7 +3625,6 @@ "version": "3.0.4", "bundled": true, "dev": true, - "optional": true, "requires": { "brace-expansion": "^1.1.7" } @@ -3616,14 +3632,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" @@ -3642,7 +3656,6 @@ "version": "0.5.1", "bundled": true, "dev": true, - "optional": true, "requires": { "minimist": "0.0.8" } @@ -3723,8 +3736,7 @@ "number-is-nan": { "version": "1.0.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "object-assign": { "version": "4.1.1", @@ -3736,7 +3748,6 @@ "version": "1.4.0", "bundled": true, "dev": true, - "optional": true, "requires": { "wrappy": "1" } @@ -3822,8 +3833,7 @@ "safe-buffer": { "version": "5.1.1", "bundled": true, - "dev": true, - "optional": true + "dev": true }, "safer-buffer": { "version": "2.1.2", @@ -3859,7 +3869,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", @@ -3879,7 +3888,6 @@ "version": "3.0.1", "bundled": true, "dev": true, - "optional": true, "requires": { "ansi-regex": "^2.0.0" } @@ -3923,14 +3931,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 } } }, @@ -4835,6 +4841,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", @@ -5610,7 +5622,6 @@ "resolved": false, "integrity": "sha1-DNkKVhCT810KmSVsIrcGlDP60Rc=", "dev": true, - "optional": true, "requires": { "kind-of": "^3.0.2", "longest": "^1.0.1", @@ -5980,8 +5991,7 @@ "version": "1.1.6", "resolved": false, "integrity": "sha512-NcdALwpXkTm5Zvvbk7owOUSvVvBKDgKP5/ewfXEznmQFfs4ZRmanOeKBTjRVjka3QFoN6XJ+9F3USqfHqTaU5w==", - "dev": true, - "optional": true + "dev": true }, "is-builtin-module": { "version": "1.0.0", @@ -6077,7 +6087,6 @@ "resolved": false, "integrity": "sha1-MeohpzS6ubuw8yRm2JOupR5KPGQ=", "dev": true, - "optional": true, "requires": { "is-buffer": "^1.1.5" } @@ -6130,8 +6139,7 @@ "version": "1.0.1", "resolved": false, "integrity": "sha1-MKCy2jj3N3DoKUoNIuZiXtd9AJc=", - "dev": true, - "optional": true + "dev": true }, "lru-cache": { "version": "4.1.3", @@ -6434,8 +6442,7 @@ "version": "1.6.1", "resolved": false, "integrity": "sha1-jcrkcOHIirwtYA//Sndihtp15jc=", - "dev": true, - "optional": true + "dev": true }, "require-directory": { "version": "2.1.1", diff --git a/package.json b/package.json index e56ee6a8..a2fc1886 100644 --- a/package.json +++ b/package.json @@ -118,6 +118,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", "mock-require": "^3.0.2", "nyc": "^13.1.0", From eb86993fb70d722c466eb1a1317f64b1cc0958cf Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Mon, 7 Jan 2019 19:24:09 +0100 Subject: [PATCH 4/6] [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 01e7dee0..567690b8 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 Server JSDoc", - "description": "UI5 Build and Development Tooling - UI5 Server", - "keyword": "openui5 sapui5 ui5 build development tool" + "title": "UI5 Build and Development Tooling - API Reference - UI5 Server", + "description": "UI5 Build and Development Tooling - API Reference - UI5 Server", + "keyword": "openui5 sapui5 ui5 build development tool api reference" }, "search": true, + "wrap": true, "menu": { "GitHub": { "href": "https://github.com/SAP/ui5-server", From ebc8e4417893ae3b3c0f08c32cdc5b970ceee153 Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Tue, 8 Jan 2019 18:56:26 +0100 Subject: [PATCH 5/6] [INTERNAL] JSDoc: Restructure modules via namespaces --- jsdoc.json | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/jsdoc.json b/jsdoc.json index 567690b8..2db1bd6d 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" From 3cdad4de1f51339bfb41624c7883848d5edf1d7b Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Wed, 9 Jan 2019 15:44:31 +0100 Subject: [PATCH 6/6] [INTERNAL] JSDoc: Refactor to use module: syntax and fix various docs --- .eslintrc.js | 2 +- index.js | 8 +- lib/middleware/discovery.js | 4 +- lib/middleware/serveIndex.js | 8 +- lib/middleware/serveResources.js | 2 +- lib/middleware/serveThemes.js | 2 +- lib/middleware/versionInfo.js | 2 +- lib/server.js | 205 ++++++++++++++++--------------- 8 files changed, 120 insertions(+), 113 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index a710d04b..c456b291 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/index.js b/index.js index 947f0bc5..74496812 100644 --- a/index.js +++ b/index.js @@ -1,4 +1,8 @@ -const ui5Server = { +/** + * @module @ui5/server + * @public + */ +module.exports = { server: require("./lib/server"), sslUtil: require("./lib/sslUtil"), middleware: { @@ -11,5 +15,3 @@ const ui5Server = { versionInfo: require("./lib/middleware/versionInfo"), } }; - -module.exports = ui5Server; diff --git a/lib/middleware/discovery.js b/lib/middleware/discovery.js index 054887a7..0de6d3b0 100644 --- a/lib/middleware/discovery.js +++ b/lib/middleware/discovery.js @@ -14,8 +14,8 @@ const urlPattern = /\/(app_pages|all_libs|all_tests)(?:[?#].*)?$/; * * @module @ui5/server/middleware/discovery * @param {Object} resourceCollections Contains the resource reader or collection to access project related files - * @param {AbstractReader} resourceCollections.source Resource reader or collection for the source project - * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies + * @param {module:@ui5/fs.AbstractReader} resourceCollections.source Resource reader or collection for the source project + * @param {module:@ui5/fs.AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies * @returns {Function} Returns a server middleware closure. */ function createMiddleware({resourceCollections}) { diff --git a/lib/middleware/serveIndex.js b/lib/middleware/serveIndex.js index fa747d32..d246f38b 100644 --- a/lib/middleware/serveIndex.js +++ b/lib/middleware/serveIndex.js @@ -10,7 +10,7 @@ const GB = KB * KB * KB; /** * Returns the mime type of the given resource * - * @param {Resource} resource the resource + * @param {module:@ui5/fs.Resource} resource the resource * @returns {string} mime type */ function getMimeType(resource) { @@ -45,7 +45,7 @@ function formatSize(bytes) { * Creates a resource info object which is used to create the HTML * content for the resource listing * - * @param {Resource} resource the resource to convert + * @param {module:@ui5/fs.Resource} resource the resource to convert * @returns {Object} resource info object */ function createResourceInfo(resource) { @@ -69,7 +69,7 @@ function createResourceInfo(resource) { /** * Creates a resource info array from the given resource array * - * @param {Resource[]} resources an array of resources + * @param {module:@ui5/fs.Resource[]} resources an array of resources * @returns {Object[]} sorted array of resource infos */ function createResourceInfos(resources) { @@ -133,7 +133,7 @@ function createContent(path, resourceInfos) { * * @module @ui5/server/middleware/serveIndex * @param {Object} resourceCollections Contains the resource reader or collection to access project related files - * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies + * @param {module:@ui5/fs.AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies * @returns {Function} Returns a server middleware closure. */ function createMiddleware({resourceCollections}) { diff --git a/lib/middleware/serveResources.js b/lib/middleware/serveResources.js index eb9755fc..a4a436ef 100644 --- a/lib/middleware/serveResources.js +++ b/lib/middleware/serveResources.js @@ -19,7 +19,7 @@ function isFresh(req, res) { * * @module @ui5/server/middleware/serveResources * @param {Object} resourceCollections Contains the resource reader or collection to access project related files - * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies + * @param {module:@ui5/fs.AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies * @returns {Function} Returns a server middleware closure. */ function createMiddleware({resourceCollections}) { diff --git a/lib/middleware/serveThemes.js b/lib/middleware/serveThemes.js index b2649f91..cd4094a4 100644 --- a/lib/middleware/serveThemes.js +++ b/lib/middleware/serveThemes.js @@ -18,7 +18,7 @@ const themeRequest = /^(.*\/)library(?:(\.css)|(-RTL\.css)|(-parameters\.json))$ * * @module @ui5/server/middleware/serveThemes * @param {Object} resourceCollections Contains the resource reader or collection to access project related files - * @param {AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies + * @param {module:@ui5/fs.AbstractReader} resourceCollections.combo Resource collection which contains the workspace and the project dependencies * @returns {Function} Returns a server middleware closure. */ function createMiddleware({resourceCollections}) { diff --git a/lib/middleware/versionInfo.js b/lib/middleware/versionInfo.js index d94c94a9..23e97d9c 100644 --- a/lib/middleware/versionInfo.js +++ b/lib/middleware/versionInfo.js @@ -5,7 +5,7 @@ const createVersionInfoProcessor = require("@ui5/builder").processors.versionInf * * @module @ui5/server/middleware/versionInfo * @param {Object} resourceCollections Contains the resource reader or collection to access project related files - * @param {AbstractReader} resourceCollections.dependencies Resource collection which contains the project dependencies + * @param {module:@ui5/fs.AbstractReader} resourceCollections.dependencies Resource collection which contains the project dependencies * @returns {Function} Returns a server middleware closure. */ function createMiddleware({resourceCollections, tree: project}) { diff --git a/lib/server.js b/lib/server.js index f5fe0fa8..39cd320c 100644 --- a/lib/server.js +++ b/lib/server.js @@ -15,105 +15,6 @@ const ui5Fs = require("@ui5/fs"); const resourceFactory = ui5Fs.resourceFactory; const ReaderCollectionPrioritized = ui5Fs.ReaderCollectionPrioritized; -/** - * Start a server for the given project (sub-)tree - * - * @public - * @module @ui5/server/server - * @param {Object} tree A (sub-)tree - * @param {Object} options Options - * @param {number} options.port Port to listen to - * @param {boolean} [options.changePortIfInUse=false] If true, change the port if it is already in use - * @param {boolean} [options.h2=false] Whether HTTP/2 should be used - defaults to http - * @param {string} [options.key] Path to private key to be used for https - * @param {string} [options.cert] Path to certificate to be used for for https - * @param {boolean} [options.acceptRemoteConnections=false] If true, listens to remote connections and not only to localhost connections - * @returns {Promise} Promise resolving once the server is listening. It resolves with an object containing the port, - * h2-flag and a close function, which can be used to stop the server. - */ -function serve(tree, {port, changePortIfInUse = false, h2 = false, key, cert, acceptRemoteConnections = false}) { - return Promise.resolve().then(() => { - const projectResourceCollections = resourceFactory.createCollectionsForTree(tree); - - const workspace = resourceFactory.createWorkspace({ - reader: projectResourceCollections.source, - name: tree.metadata.name - }); - - const combo = new ReaderCollectionPrioritized({ - name: "server - prioritize workspace over dependencies", - readers: [workspace, projectResourceCollections.dependencies] - }); - - const resourceCollections = { - source: projectResourceCollections.source, - dependencies: projectResourceCollections.dependencies, - combo - }; - - const app = express(); - - const oCspConfig = { - allowDynamicPolicySelection: true, - allowDynamicPolicyDefinition: true, - defaultPolicyIsReportOnly: true, - definedPolicies: { - "sap-target-level-1": - "default-src 'self'; " + - "script-src 'self' 'unsafe-eval'; " + - "style-src 'self' 'unsafe-inline'; " + - "font-src 'self' data:; " + - "img-src 'self' * data: blob:; " + - "frame-src 'self' https: data: blob:; " + - "child-src 'self' https: data: blob:; " + - "connect-src 'self' https: wss:;", - "sap-target-level-2": - "default-src 'self'; " + - "script-src 'self'; " + - "style-src 'self' 'unsafe-inline'; " + - "font-src 'self' data:; " + - "img-src 'self' * data: blob:; " + - "frame-src 'self' https: data: blob:; " + - "child-src 'self' https: data: blob:; " + - "connect-src 'self' https: wss:;" - } - }; - app.use(csp("sap-ui-xx-csp-policy", oCspConfig)); - - app.use(compression()); - app.use(cors()); - - app.use("/discovery", discovery({resourceCollections})); - app.use(serveResources({resourceCollections})); - app.use(serveThemes({resourceCollections})); - app.use("/resources/sap-ui-version.json", versionInfo({resourceCollections, tree})); - - app.use("/proxy", ui5connect.proxy({ - secure: false - })); - - // Handle anything but read operations *before* the serveIndex middleware - // as it will reject them with a 405 (Method not allowed) instead of 404 like our old tooling - app.use(nonReadRequests({resourceCollections})); - app.use(serveIndex({resourceCollections})); - - if (h2) { - return _addSsl({app, h2, key, cert}); - } - return app; - }).then((app) => { - return _listen(app, port, changePortIfInUse, acceptRemoteConnections).then(function({port, server}) { - return { - h2, - port, - close: function(callback) { - server.close(callback); - } - }; - }); - }); -} - /** * Returns a promise resolving by starting the server. * @@ -184,6 +85,110 @@ function _addSsl({app, key, cert}) { return require("spdy").createServer({cert, key}, app); } +/** + * @public + * @namespace + * @alias module:@ui5/server.server + */ module.exports = { - serve: serve + /** + * Start a server for the given project (sub-)tree + * + * @public + * @param {Object} tree A (sub-)tree + * @param {Object} options Options + * @param {number} options.port Port to listen to + * @param {boolean} [options.changePortIfInUse=false] If true, change the port if it is already in use + * @param {boolean} [options.h2=false] Whether HTTP/2 should be used - defaults to http + * @param {string} [options.key] Path to private key to be used for https + * @param {string} [options.cert] Path to certificate to be used for for https + * @param {boolean} [options.acceptRemoteConnections=false] If true, listens to remote connections and + * not only to localhost connections + * @returns {Promise} Promise resolving once the server is listening. + * It resolves with an object containing the port, + * h2-flag and a close function, + * which can be used to stop the server. + */ + serve(tree, {port, changePortIfInUse = false, h2 = false, key, cert, acceptRemoteConnections = false}) { + return Promise.resolve().then(() => { + const projectResourceCollections = resourceFactory.createCollectionsForTree(tree); + + const workspace = resourceFactory.createWorkspace({ + reader: projectResourceCollections.source, + name: tree.metadata.name + }); + + const combo = new ReaderCollectionPrioritized({ + name: "server - prioritize workspace over dependencies", + readers: [workspace, projectResourceCollections.dependencies] + }); + + const resourceCollections = { + source: projectResourceCollections.source, + dependencies: projectResourceCollections.dependencies, + combo + }; + + const app = express(); + + const oCspConfig = { + allowDynamicPolicySelection: true, + allowDynamicPolicyDefinition: true, + defaultPolicyIsReportOnly: true, + definedPolicies: { + "sap-target-level-1": + "default-src 'self'; " + + "script-src 'self' 'unsafe-eval'; " + + "style-src 'self' 'unsafe-inline'; " + + "font-src 'self' data:; " + + "img-src 'self' * data: blob:; " + + "frame-src 'self' https: data: blob:; " + + "child-src 'self' https: data: blob:; " + + "connect-src 'self' https: wss:;", + "sap-target-level-2": + "default-src 'self'; " + + "script-src 'self'; " + + "style-src 'self' 'unsafe-inline'; " + + "font-src 'self' data:; " + + "img-src 'self' * data: blob:; " + + "frame-src 'self' https: data: blob:; " + + "child-src 'self' https: data: blob:; " + + "connect-src 'self' https: wss:;" + } + }; + app.use(csp("sap-ui-xx-csp-policy", oCspConfig)); + + app.use(compression()); + app.use(cors()); + + app.use("/discovery", discovery({resourceCollections})); + app.use(serveResources({resourceCollections})); + app.use(serveThemes({resourceCollections})); + app.use("/resources/sap-ui-version.json", versionInfo({resourceCollections, tree})); + + app.use("/proxy", ui5connect.proxy({ + secure: false + })); + + // Handle anything but read operations *before* the serveIndex middleware + // as it will reject them with a 405 (Method not allowed) instead of 404 like our old tooling + app.use(nonReadRequests({resourceCollections})); + app.use(serveIndex({resourceCollections})); + + if (h2) { + return _addSsl({app, h2, key, cert}); + } + return app; + }).then((app) => { + return _listen(app, port, changePortIfInUse, acceptRemoteConnections).then(function({port, server}) { + return { + h2, + port, + close: function(callback) { + server.close(callback); + } + }; + }); + }); + } };