From 7f5aa78c2d6432e68d512955ba6c2530a5f41edc Mon Sep 17 00:00:00 2001
From: Nicolas Coden <nicolas@ncoden.fr>
Date: Thu, 29 Nov 2018 23:57:52 +0100
Subject: [PATCH] docs: add documentation for the webpack UMD configuration

---
 gulp/tasks/javascript.js | 16 +++++++++++++++-
 gulp/utils.js            | 14 ++++++++++++++
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/gulp/tasks/javascript.js b/gulp/tasks/javascript.js
index 22919b7e8..d6452b6de 100644
--- a/gulp/tasks/javascript.js
+++ b/gulp/tasks/javascript.js
@@ -16,7 +16,18 @@ var CONFIG = require('../config.js');
 // (just throw in foundation.js or foundation.min.js) or you should be using a build
 // system.
 
-// Generate plugin Externals config for UMD modules
+//
+// Generate the webpack "Externals" configuration for UMD modules.
+// This tells webpack that the modules imported with the listed paths should not
+// be included in the build but will be provided later from an external source.
+//
+// `umdExternals` generates for each module a configuration object with the
+// given external source path/object to indicate to all import solutions where
+// to retrieve the module. "root" is the global variable name to use in
+// module-less environments (or in the namespace if given).
+//
+// See https://webpack.js.org/configuration/externals/#externals
+//
 var webpackExternalPlugins = Object.assign(
   utils.umdExternals({
     // Use the global jQuery object "jQuery" in module-less environments.
@@ -47,6 +58,9 @@ var webpackExternalPlugins = Object.assign(
   })
 );
 
+// The webpack "output" configuration for UMD modules.
+// Makes the modules be exported as UMD modules and within this global
+// variable in module-less environments.
 var webpackOutputAsExternal = {
   library: [CONFIG.JS_BUNDLE_NAMESPACE, '[name]'],
   libraryTarget: 'umd',
diff --git a/gulp/utils.js b/gulp/utils.js
index 30dba17b5..66105afe6 100644
--- a/gulp/utils.js
+++ b/gulp/utils.js
@@ -23,6 +23,20 @@ function getUmdEntry(name, config, format) {
   return name;
 }
 
+/**
+ * Generate an configuration object for Webpack Externals for UMD modules.
+ * See: https://webpack.js.org/configuration/externals/#object
+ *
+ * @param {object} externals - Configuration object for external UMD modules.
+ *  For each entry, a string or an object can be provided.
+ *  - If a string, it is used for all module formats.
+ *  - If an object, it is used as is and the module name is used for missing formats.
+ * @param {object} {} options- Additional options:
+ *  - namespace {string} '' - Global variable in which the modules must be
+ *    searched in instead of the root for module-less environments.
+ *
+ * @return {object} Generated configuration for Webpack Externals
+ */
 module.exports.umdExternals = function(externals, options) {
   options = Object.assign({ namespace: '' }, options);
 
-- 
2.47.2