From 1919fa41b6da4dfd4f69e776caa6e6b1883eb208 Mon Sep 17 00:00:00 2001 From: Maximilian Krambach Date: Wed, 4 Jul 2018 13:38:54 +0200 Subject: [PATCH] js: Add jsdoc, update webpack-cli dependency -- * package.json: - the old webpack-cli version depended on two packages with vulnerabilities, set to minimum version 3.0.8 to fix this (nodesecurity.io/advisories/157, nodesecurity.io/advisories/612) - added License identifier * README: Updated documentation * jsdoc.conf: Added a configuration file for jsdoc * some minor documentation changes, indentations --- lang/js/README | 94 ++++++++++++++++++++----------- lang/js/README_testing | 14 ----- lang/js/jsdoc.conf | 24 ++++++++ lang/js/package.json | 7 ++- lang/js/src/Connection.js | 7 ++- lang/js/src/Keyring.js | 6 +- lang/js/webpack.conf.js | 21 +++---- lang/js/webpack.conf_unittests.js | 20 ++++--- 8 files changed, 119 insertions(+), 74 deletions(-) delete mode 100644 lang/js/README_testing create mode 100644 lang/js/jsdoc.conf diff --git a/lang/js/README b/lang/js/README index b597adb2..86d2616a 100644 --- a/lang/js/README +++ b/lang/js/README @@ -3,50 +3,80 @@ of gnupg in browsers, with the help of nativeMessaging. Installation ------------- -gpgmejs uses webpack, and thus depends on nodejs for building. Webpack can be -installed by running -`npm install webpack webpack-cli --save-dev`. +gpgmejs uses webpack, and thus depends on nodejs for building. All dependencies +will be installed (in a local subdirectory) with the command `npm install`. To create a current version of the package, the command is `npx webpack --config webpack.conf.js`. If you want a more debuggable (i.e. not minified) build, just change the mode in webpack.conf.js. -Demo WebExtension: -As soon as a bundled webpack is in dist/ -the gpgmejs folder can just be included in the extensions tab of the browser in -questions (extension debug mode needs to be active). For chrome, selecting the -folder is sufficient, for firefox, the manifest.json needs to be selected. +Demo and Test WebExtension: +--------------------------- + +The Demo Extension shows simple examples of the usage of gpgmejs. + +The BrowsertestExtension runs more intensive tests (using the mocha and chai +frameworks). Tests from BrowserTestExtension/tests will be run against the +gpgmejs.bundle.js itself. They aim to test the outward facing functionality +and API. + +Unittests as defined in ./unittests.js will be bundled in +gpgmejs_unittests.bundle.js, and test the separate components of gpgmejs, +which mostly are not exported. + +. The file `build_extension.sh` may serve as a pointer on how to +build and assemble these two Extensions and their dependencies. It can directly +be used in most linux systems. + +The resulting folders can just be included in the extensions tab of the browser +in questions (extension debug mode needs to be active). For chrome, selecting +the folder is sufficient, for firefox, the manifest.json needs to be selected. Please note that it is just for demonstration/debug purposes! +For the Extensions to successfully communicate with gpgme-json, a manifest file +is needed. + +- `~/.config/chromium/NativeMessagingHosts/gpgmejson.json` + In the browsers' nativeMessaging configuration folder a file 'gpgmejs.json' is needed, with the following content: -(The path to the native app gpgme-json may need adaption) +- For Chrome/Chromium: + ``` + { + "name": "gpgmejson", + "description": "This is a test application for gpgmejs", + "path": "/usr/bin/gpgme-json", + "type": "stdio", + "allowed_origins": ["chrome-extension://ExtensionIdentifier/"] + } + ``` + The usual path for Linux is similar to: + `~/.config/chromium/NativeMessagingHosts/gpgmejson.json` for + For Windows, the path to the manifest needs to be placed in + `HKEY_LOCAL_MACHINE\SOFTWARE\Google\Chrome\NativeMessagingHosts\gpgmejson` -Chromium: -~/.config/chromium/NativeMessagingHosts/gpgmejson.json + - For firefox: + ``` + { + "name": "gpgmejson", + "description": "This is a test application for gpgmejs", + "path": "/usr/bin/gpgme-json", + "type": "stdio", + "allowed_extensions": ["ExtensionIdentifier@temporary-addon"] + } + ``` -{ - "name": "gpgmejson", - "description": "This is a test application for gpgmejs", - "path": "/usr/bin/gpgme-json", - "type": "stdio", - "allowed_origins": ["chrome-extension://ExtensionIdentifier/"] -} -The ExtensionIdentifier can be seen on the chrome://extensions page, and -changes on each reinstallation. Note the slashes in allowed_origins. + The ExtensionIdentifier can be seen as Extension ID on the about:addons page + if addon-debugging is active. In firefox, the temporary addon is removed once + firefox exits, and the identifier will need to be changed more often. + The manifest for linux is usually placed at: + `~/.mozilla/native-messaging-hosts/gpgmejson.json` -Firefox: -~/.mozilla/native-messaging-hosts/gpgmejson.json -{ - "name": "gpgmejson", - "description": "This is a test application for gpgmejs", - "path": "/usr/bin/gpgme-json", - "type": "stdio", - "allowed_extensions": ["ExtensionIdentifier@temporary-addon"] -} -The ExtensionIdentifier can be seen as Extension ID on the about:addons page if -addon-debugging is active. In firefox, the temporary addon is removed once -firefox exits, and the identifier will need to be changed more often. +Documentation +------------- + +The documentation can be built by jsdoc. It currently uses the command +`./node_modules/.bin/jsdoc -c jsdoc.conf`. diff --git a/lang/js/README_testing b/lang/js/README_testing deleted file mode 100644 index b61ca1a6..00000000 --- a/lang/js/README_testing +++ /dev/null @@ -1,14 +0,0 @@ -Test extension: - -The test extension contains tests with mocha and chai. It will be packed as an -extra extension (see build_extension.sh). - -Tests from BrowserTestExtension/tests will be run against the gpgmejs.bundle.js -itself. They aim to test the outward facing functionality and API. - -Unittests as defined in ./unittests.js will be bundled in -gpgmejs_unittests.bundle.js, and test the separate components of gpgmejs, -which mostly are not exported. - -The BrowserExtension can be installed the same way as the DemoExtension -(see README). \ No newline at end of file diff --git a/lang/js/jsdoc.conf b/lang/js/jsdoc.conf new file mode 100644 index 00000000..12ae35e9 --- /dev/null +++ b/lang/js/jsdoc.conf @@ -0,0 +1,24 @@ +{ + "tags": { + "allowUnknownTags": false, + "dictionaries": ["jsdoc"] + }, + "source": { + "include": ["./src"], + "includePattern": ".+\\.js(doc|x)?$", + "excludePattern": "(^|\\/|\\\\)_" + }, + "opts":{ + "destination": "./doc/", + "recurse": true + }, + "sourceType": "module", + "plugins": [], + "templates": { + "cleverLinks": false, + "monospaceLinks": false, + "default": { + "outputSourceFiles": true + } + } +} \ No newline at end of file diff --git a/lang/js/package.json b/lang/js/package.json index acf89117..54af2982 100644 --- a/lang/js/package.json +++ b/lang/js/package.json @@ -6,11 +6,12 @@ "private": true, "keywords": [], "author": "", - "license": "", + "license": "LGPL-2.1+", "devDependencies": { "webpack": "^4.5.0", - "webpack-cli": "^2.0.14", + "webpack-cli": "^3.0.8", "chai": "^4.1.2", - "mocha": "^5.1.1" + "mocha": "^5.1.1", + "jsdoc": "^3.5.5" } } diff --git a/lang/js/src/Connection.js b/lang/js/src/Connection.js index f399b22b..945932e9 100644 --- a/lang/js/src/Connection.js +++ b/lang/js/src/Connection.js @@ -40,9 +40,10 @@ export class Connection{ * Retrieves the information about the backend. * @param {Boolean} details (optional) If set to false, the promise will * just return a connection status - * @returns {Promise} - * {String} The property 'gpgme': Version number of gpgme - * {Array} 'info' Further information about the backends. + * @returns {Promise} result + * @returns {String} result.gpgme Version number of gpgme + * @returns {Array} result.info Further information about the + * backends. * Example: * "protocol": "OpenPGP", * "fname": "/usr/bin/gpg", diff --git a/lang/js/src/Keyring.js b/lang/js/src/Keyring.js index 0d7643f0..358757b0 100644 --- a/lang/js/src/Keyring.js +++ b/lang/js/src/Keyring.js @@ -110,10 +110,10 @@ export class GPGME_Keyring { * contains a secret key. * @returns {Promise} * - * @async + * * TODO: getHasSecret always returns false at this moment, so this fucntion * still does not fully work as intended. - * + * * @async */ getDefaultKey() { let me = this; @@ -283,7 +283,7 @@ export class GPGME_Keyring { * @param {Date} expires (optional) Expiration date. If not set, expiration * will be set to 'never' * - * @returns{Promise} + * @return {Promise} */ generateKey(userId, algo = 'default', expires){ if ( diff --git a/lang/js/webpack.conf.js b/lang/js/webpack.conf.js index b2ad9098..19f3bbda 100644 --- a/lang/js/webpack.conf.js +++ b/lang/js/webpack.conf.js @@ -19,17 +19,18 @@ * * This is the configuration file for building the gpgmejs-Library with webpack */ +/* global require, module, __dirname */ const path = require('path'); module.exports = { - entry: './src/index.js', - // mode: 'development', - mode: 'production', - output: { - path: path.resolve(__dirname, 'build'), - filename: 'gpgmejs.bundle.js', - libraryTarget: 'var', - libraryExport: 'default', - library: 'Gpgmejs' - } + entry: './src/index.js', + // mode: 'development', + mode: 'production', + output: { + path: path.resolve(__dirname, 'build'), + filename: 'gpgmejs.bundle.js', + libraryTarget: 'var', + libraryExport: 'default', + library: 'Gpgmejs' + } }; diff --git a/lang/js/webpack.conf_unittests.js b/lang/js/webpack.conf_unittests.js index 4b903be6..c3c87f39 100644 --- a/lang/js/webpack.conf_unittests.js +++ b/lang/js/webpack.conf_unittests.js @@ -19,16 +19,18 @@ * * This is the configuration file for building the gpgmejs-Library with webpack */ +/* global require, module, __dirname */ + const path = require('path'); module.exports = { - entry: './unittests.js', - mode: 'production', - output: { - path: path.resolve(__dirname, 'build'), - filename: 'gpgmejs_unittests.bundle.js', - libraryTarget: 'var', - libraryExport: 'default', - library: 'Gpgmejs_test' - } + entry: './unittests.js', + mode: 'production', + output: { + path: path.resolve(__dirname, 'build'), + filename: 'gpgmejs_unittests.bundle.js', + libraryTarget: 'var', + libraryExport: 'default', + library: 'Gpgmejs_test' + } };