docs: add documentation for the webpack UMD configuration

diff --git a/gulp/tasks/javascript.js b/gulp/tasks/javascript.js
index 22919b7e8d5c402192b8dfe29d0b17916c24631c..d6452b6de9857b9c3dfd9c6b4d4fb946cf4b2282 100644 (file)
--- 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 30dba17b58fa9cb886cf9c74a565ebefe6f804eb..66105afe63d4b8568d8ba954d667354a824d8594 100644 (file)
--- 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);