Add comments to example authorisation plugins

other/js/auth_plugin_examples.js

@@ -10,9 +10,20 @@
  */
 
 const querystring = require('querystring');
-fs = require('fs');
+const fs = require('fs');
 
 function urlTokenMatch(url, token, verbose=false) {
+    /**
+     * Parse the url path, extract the `token` querystring value, and check if
+     * it matches the token argument. If verbose is set to true, log messages
+     * are enabled.
+     *
+     * Args:
+     *      url (string): the path section of the URL
+     *      token (string): the token which the token provided in the URL should
+     *          match
+     *      verbose (boolean): If True, extra console.log messages will be output
+     */
     let splitUrl = url.split("?")
     if (splitUrl.length !== 2) {
         if (verbose) {
@@ -34,6 +45,11 @@ function urlTokenMatch(url, token, verbose=false) {
 }
 
 exports.tokenAuth = function tokenAuth(source) {
+    /**
+     * Authorisation plugin which validates the token query parameter against
+     * a token provided as the argument to the --auth-source command line
+     * argument
+     */
     return function(info) {
         let token = source;
         return urlTokenMatch(info.req.url, token, true);
@@ -41,6 +57,12 @@ exports.tokenAuth = function tokenAuth(source) {
 }
 
 exports.tokenAuthEnv = function tokenAuthEnv(source) {
+    /**
+     * Authorisation plugin which validates the token query parameter against
+     * a token which is the value of an environment variable. The name of this
+     * environment variable is specified as the argument to the command line
+     * argument --auth-source
+     */
     return function(info) {
         let token = process.env[source];
         return urlTokenMatch(info.req.url, token, true);
@@ -48,6 +70,11 @@ exports.tokenAuthEnv = function tokenAuthEnv(source) {
 }
 
 exports.tokenAuthFile = function tokenEnvFile(source) {
+    /**
+     * Authorisation plugin which validates the token query parameter against a
+     * token which is contained in a text file, the path to which is specified
+     * as the value of the --auth-source command line argument
+     */
     return function(info, cb) {
         fs.readFile(source, 'utf8', function(err, data) {
             if (err) {