[INTERNAL] Update and add more jsdoc for server, sslUtil and middleware

Author: svbender

lib/middleware/discovery.js

@@ -2,6 +2,22 @@ const librariesPattern = /([A-Z0-9._%+-/]+)\/[A-Z0-9._]*\.library$/i;
 const testPagesPattern = /(([A-Z0-9._%+-]+\/)+([A-Z_0-9-\\.]+)\.(html|htm))$/i;
 const urlPattern = /\/(app_pages|all_libs|all_tests)(?:[?#].*)?$/;
 
+/**
+ * Creates and returns the middleware to discover project files.
+ *
+ * List project files with URL (needed exclusively by the OpenUI5 testsuite):
+ * <ul>
+ * <li>/discovery/app_pages: get application pages</li>
+ * <li>/discovery/all_libs: list all libraries</li>
+ * <li>/discovery/all_tests: list all tests</li>
+ * </ul>
+ *
+ * @module 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
+ * @returns {function} Returns a server middleware closure.
+ */
 function createMiddleware({resourceCollections}) {
 	return function discoveryMiddleware(req, res, next) {
 		var parts = urlPattern.exec(req.url);

lib/middleware/nonReadRequests.js

@@ -1,4 +1,13 @@
-function createMiddleware({resourceCollections}) {
+/**
+ * Creates and returns the middleware to handle non read requests.
+ *
+ * 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
+ * @returns {function} Returns a server middleware closure.
+ */
+function createMiddleware() {
 	return function nonReadRequests(req, res, next) {
 		// 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

lib/middleware/serveResources.js

@@ -13,6 +13,15 @@ function isFresh(req, res) {
 	});
 }
 
+
+/**
+ * Creates and returns the middleware to serve application resources.
+ *
+ * @module 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.
+ */
 function createMiddleware({resourceCollections}) {
 	return function serveResources(req, res, next) {
 		resourceCollections.combo.byPath(req.path).then(function(resource) {

lib/middleware/serveThemes.js

@@ -11,6 +11,16 @@ function isFresh(req, res) {
 
 const themeRequest = /^(.*\/)library(?:(\.css)|(-RTL\.css)|(-parameters\.json))$/i;
 
+/**
+ * Creates and returns the middleware to build themes.
+ *
+ * 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
+ * @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.
+ */
 function createMiddleware({resourceCollections}) {
 	const builder = new themeBuilder.ThemeBuilder({
 		fs: fsInterface(resourceCollections.combo)

lib/middleware/versionInfo.js

@@ -1,5 +1,13 @@
 const createVersionInfoProcessor = require("@ui5/builder").processors.versionInfoGenerator;
 
+/**
+ * Creates and returns the middleware to create the version info as json object.
+ *
+ * @module 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.
+ */
 function createMiddleware({resourceCollections, tree: project}) {
 	return function versionInfo(req, res, next) {
 		resourceCollections.dependencies.byGlob("/**/.library")

lib/server.js

@@ -19,15 +19,16 @@ const fsInterface = ui5Fs.fsInterface;
  * Start a server for the given project (sub-)tree
  *
  * @module server/server
- * @param      {Object}   tree       	A (sub-)tree
- * @param      {Object}   options       Options
- * @param      {string}   options.port  Port to listen to
- * @param      {boolean}  [options.changePortIfInUse=false]  If true, change the port if it is already in use
- * @param      {string}   [options.protocol=http]  Protocol to be used (http|https|h2) - defaults to <pre>http</pre>
- * @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
-
- * @returns     {Promise}  Promise resolving with an object containing the <pre>port</pre> once the server is listening
+ * @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 <code>http</code>
+ * @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<Object>} Promise resolving once the server is listening. It resolves with an object containing the <code>port</code>,
+ *                            <code>h2</code>-flag and a <code>close</code> 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(() => {
@@ -72,7 +73,7 @@ function serve(tree, {port, changePortIfInUse = false, h2 = false, key, cert, ac
 		}));
 
 		if (h2) {
-			return addSsl({app, h2, key, cert});
+			return _addSsl({app, h2, key, cert});
 		}
 		return app;
 	}).then((app) => {
@@ -88,6 +89,16 @@ function serve(tree, {port, changePortIfInUse = false, h2 = false, key, cert, ac
 	});
 }
 
+/**
+ * Returns a promise resolving by starting the server.
+ *
+ * @param {Object} app The express applicaton object
+ * @param {number} port Desired port to listen to
+ * @param {boolean} changePortIfInUse If true and the port is already in use, an unused port is searched
+ * @param {boolean} acceptRemoteConnections If true, listens to remote connections and not only to localhost connections
+ * @returns {Promise<Object>} Returns an object containing server related information like (selected port, protocol)
+ * @private
+ */
 function _listen(app, port, changePortIfInUse, acceptRemoteConnections) {
 	return new Promise(function(resolve, reject) {
 		const options = {};
@@ -132,7 +143,16 @@ function _listen(app, port, changePortIfInUse, acceptRemoteConnections) {
 	});
 }
 
-function addSsl({app, protocol, key, cert}) {
+/**
+ * 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
+ * @returns {Object} The express application with SSL support
+ * @private
+ */
+function _addSsl({app, key, cert}) {
 	// Using spdy as http2 server as the native http2 implementation
 	// from Node v8.4.0 doesn't seem to work with express
 	return require("spdy").createServer({cert, key}, app);

lib/sslUtil.js

@@ -14,15 +14,19 @@ var prompt = require("prompt");
 
 const sslUtil = {
 	/**
-	 * @param      {string}   [keyPath=$HOME/.ui5/server/server.key]  Path to private key to be used for https.
-	 *                          Defaults to <pre>$HOME/.ui5/server/server.key</pre>
-	 * @param      {string}   [certPath=$HOME/.ui5/server/server.crt]  Path to certificate to be used for for https.
-	 *                          Defaults to <pre>$HOME/.ui5/server/server.crt</pre>
-	 * @returns {Promise.<object>} Resolves with an sslObject containing <pre>cert</pre> and <pre>key</pre>
+	 * Creates a new SSL certificate or validates an existing one.
+	 *
+	 * @module server/sslUtil
+	 * @param {string} [keyPath=$HOME/.ui5/server/server.key]  Path to private key to be used for https.
+	 *                                                         Defaults to <code>$HOME/.ui5/server/server.key</code>
+	 * @param {string} [certPath=$HOME/.ui5/server/server.crt] Path to certificate to be used for for https.
+	 *                                                         Defaults to <code>$HOME/.ui5/server/server.crt</codee>
+	 * @returns {Promise<object>} Resolves with an sslObject containing <code>cert</code> and <code>key</code>
 	 */
 	getSslCertificate: function(
 		keyPath = path.join(os.homedir(), ".ui5/server/server.key"),
-		certPath = path.join(os.homedir(), ".ui5/server/server.crt")) {
+		certPath = path.join(os.homedir(), ".ui5/server/server.crt")
+	) {
 		// checks the certificates if they are present
 		return Promise.all([
 			fileExists(keyPath).then((bExists) => {