docs: add documentation for the webpack UMD configuration

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',

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);