JavaScriptExample
diff --git a/‎lib/optimize/CommonsChunkPlugin.js‎
Lines changed: 48 additions & 42 deletions b/‎lib/optimize/CommonsChunkPlugin.js‎
Lines changed: 48 additions & 42 deletions
@@ -60,7 +60,8 @@ The available options are:
 		 * that webpack will take care of loading this file.
 		 */
 		if(options.async && options.filename) {
-			throw new Error("If you set the \"async\" option webpack takes care of loading the chunk. Therefore you can not specify a filename.");
+			throw new Error(`You can not specify a filename if you use the \"async\" option.
+You can however specify the name of the async chunk by passing the desired string as the \"async\" option.`);
 		}
 
 		const chunkNames = options.name ? [options.name] : options.names;
@@ -89,78 +90,83 @@ The available options are:
 				compilation[ident] = true;
 
 				/**
-				 * Creates a list of common chunks based on the options.
+				 * Creates a list of "common"" chunks based on the options.
 				 * The list is made up of preexisting or newly created chunks.
 				 * - If chunk has the name as specified in the chunkNames it is put in the list
 				 * - If no chunk with the name as given in chunkNames exists a new chunk is created and added to the list
+				 *
+				 * These chunks are the "targets" for extracted modules.
 				 */
-				const commonChunks = this.getCommonChunks(chunks, compilation, this.chunkNames, this.children, this.async);
+				const targetChunks = this.getTargetChunks(chunks, compilation, this.chunkNames, this.children, this.async);
 
 				// iterate over all our new chunks
-				commonChunks.forEach((commonChunk, idx) => {
-					// get chunks that are actually used
-					// TODO: clarify what that means
-					const usedChunks = this.getUsedChunks(compilation, chunks, commonChunk, commonChunks, idx, this.selectedChunks, this.async, this.children);
+				targetChunks.forEach((targetChunk, idx) => {
 
-					// bail as this is an erronous state
-					if(!usedChunks) {
+					/**
+					 * These chunks are subject to get "common" modules extracted and moved to the common chunk
+					 */
+					const affectedChunks = this.getAffectedChunks(compilation, chunks, targetChunk, targetChunks, idx, this.selectedChunks, this.async, this.children);
+
+					// bail if no chunk is affected
+					if(!affectedChunks) {
 						return;
 					}
 
 					// If we are async create an async chunk now
 					// override the "commonChunk" with the newly created async one and use it as commonChunk from now on
 					let asyncChunk;
 					if(asyncOption) {
-						asyncChunk = this.createAsyncChunk(compilation, this.async, commonChunk);
-						commonChunk.addChunk(asyncChunk);
-						commonChunk = asyncChunk;
+						asyncChunk = this.createAsyncChunk(compilation, this.async, targetChunk);
+						targetChunk.addChunk(asyncChunk);
+						targetChunk = asyncChunk;
 					}
 
-					// get all modules that suffice the filter e.g. are used at least in "n" chunks
-					// TODO: what does "really used modules mean here"?
-					const reallyUsedModules = this.getReallyUsedModules(minChunks, usedChunks, commonChunk);
+					/**
+					 * Check which modules are "common" and could be extracted to a "common" chunk
+					 */
+					const extractableModules = this.getExtractableModules(minChunks, affectedChunks, targetChunk);
 
 					// If the minSize option is set check if the size extracted from the chunk is reached
 					// else bail out here.
 					// As all modules/commons are interlinked with each other, common modules would be extracted
 					// if we reach this mark at a later common chunk. (quirky I guess).
 					if(minSize) {
-						const modulesSize = this.getModulesSize(reallyUsedModules);
+						const modulesSize = this.calculateModuleSize(extractableModules);
 						// if too small, bail
 						if(modulesSize < minSize)
 							return;
 					}
 
 					// Remove modules that are moved to commons chunk from their original chunks
 					// return all chunks that are affected by having modules removed - we need them later (apparently)
-					const reallyUsedChunks = this.removeModulesFromUsedChunksAndReturnUsedChunks(reallyUsedModules, usedChunks);
+					const chunksWithExtractedModules = this.extractModulesAndReturnAffectedChunks(extractableModules, affectedChunks);
 
 					// connect all extracted modules with the common chunk
-					this.connectModulesWithCommonChunk(commonChunk, reallyUsedModules);
+					this.addExtractedModulesToTargetChunk(targetChunk, extractableModules);
 
 					// set filenameTemplate for chunk
 					if(filenameTemplate)
-						commonChunk.filenameTemplate = filenameTemplate;
+						targetChunk.filenameTemplate = filenameTemplate;
 
 					// if we are async connect the blocks of the "reallyUsedChunk" - the ones that had modules removed -
 					// with the commonChunk and get the origins for the asyncChunk (remember "asyncChunk === commonChunk" at this moment).
 					// bail out
 					if(asyncOption) {
-						this.connectChunkBlocksWithCommonChunk(reallyUsedChunks, commonChunk);
-						asyncChunk.origins = this.getAsyncChunkOrigin(reallyUsedChunks);
+						this.moveExtractedChunkBlocksToTargetChunk(chunksWithExtractedModules, targetChunk);
+						asyncChunk.origins = this.extractOriginsOfChunksWithExtractedModules(chunksWithExtractedModules);
 						return;
 					}
 
 					// we are not in "async" mode
 					// connect used chunks with commonChunk - shouldnt this be reallyUsedChunks here?
-					this.addCommonChunkAsParentOfAffectedChunks(usedChunks, commonChunk);
+					this.makeTargetChunkParentOfAffectedChunks(affectedChunks, targetChunk);
 				});
 				return true;
 			});
 		});
 	}
 
-	getCommonChunks(allChunks, compilation, chunkNames, children, asyncOption) {
+	getTargetChunks(allChunks, compilation, chunkNames, children, asyncOption) {
 		const asyncOrNoSelectedChunk = children || asyncOption;
 
 		// we have specified chunk names
@@ -191,24 +197,24 @@ The available options are:
 		throw new Error("Invalid chunkNames argument");
 	}
 
-	getUsedChunks(compilation, allChunks, commonChunk, commonChunks, currentIndex, selectedChunks, asyncOption, children) {
+	getAffectedChunks(compilation, allChunks, targetChunk, targetChunks, currentIndex, selectedChunks, asyncOption, children) {
 		const asyncOrNoSelectedChunk = children || asyncOption;
 
 		if(Array.isArray(selectedChunks)) {
 			return allChunks.filter(chunk => {
-				const notCommmonChunk = chunk !== commonChunk;
+				const notCommmonChunk = chunk !== targetChunk;
 				const isSelectedChunk = selectedChunks.indexOf(chunk.name) > -1;
 				return notCommmonChunk && isSelectedChunk;
 			});
 		}
 
 		if(asyncOrNoSelectedChunk) {
 			// nothing to do here
-			if(!commonChunk.chunks) {
+			if(!targetChunk.chunks) {
 				return [];
 			}
 
-			return commonChunk.chunks.filter((chunk) => {
+			return targetChunk.chunks.filter((chunk) => {
 				// we can only move modules from this chunk if the "commonChunk" is the only parent
 				return asyncOption || chunk.parents.length === 1;
 			});
@@ -217,30 +223,30 @@ The available options are:
 		/**
 		 * past this point only entry chunks are allowed to become commonChunks
 		 */
-		if(commonChunk.parents.length > 0) {
-			compilation.errors.push(new Error("CommonsChunkPlugin: While running in normal mode it's not allowed to use a non-entry chunk (" + commonChunk.name + ")"));
+		if(targetChunk.parents.length > 0) {
+			compilation.errors.push(new Error("CommonsChunkPlugin: While running in normal mode it's not allowed to use a non-entry chunk (" + targetChunk.name + ")"));
 			return;
 		}
 
 		// what is this?
 		return allChunks.filter((chunk) => {
-			const found = commonChunks.indexOf(chunk);
+			const found = targetChunks.indexOf(chunk);
 			if(found >= currentIndex) return false;
 			return chunk.hasRuntime();
 		});
 	}
 
-	createAsyncChunk(compilation, asyncOption, commonChunk) {
+	createAsyncChunk(compilation, asyncOption, targetChunk) {
 		const asyncChunk = compilation.addChunk(typeof asyncOption === "string" ? asyncOption : undefined);
 		asyncChunk.chunkReason = "async commons chunk";
 		asyncChunk.extraAsync = true;
-		asyncChunk.addParent(commonChunk);
+		asyncChunk.addParent(targetChunk);
 		return asyncChunk;
 	}
 
 	// If minChunks is a function use that
 	// otherwhise check if a module is used at least minChunks or 2 or usedChunks.length time
-	getModuleFilter(minChunks, commonChunk, usedChunksLength) {
+	getModuleFilter(minChunks, targetChunk, usedChunksLength) {
 		if(typeof minChunks === "function") {
 			return minChunks;
 		}
@@ -249,7 +255,7 @@ The available options are:
 		return isUsedAtLeastMinTimes;
 	}
 
-	getReallyUsedModules(minChunks, usedChunks, commonChunk) {
+	getExtractableModules(minChunks, usedChunks, targetChunk) {
 		if(minChunks === Infinity) {
 			return [];
 		}
@@ -264,7 +270,7 @@ The available options are:
 		}, new Map());
 
 		// filter by minChunks
-		const moduleFilterCount = this.getModuleFilter(minChunks, commonChunk, usedChunks.length);
+		const moduleFilterCount = this.getModuleFilter(minChunks, targetChunk, usedChunks.length);
 		// filter by condition
 		const moduleFilterCondition = (module, chunk) => {
 			if(!module.chunkCondition) {
@@ -277,15 +283,15 @@ The available options are:
 			const module = entry[0];
 			const count = entry[1];
 			// if the module passes both filters, keep it.
-			return moduleFilterCount(module, count) && moduleFilterCondition(module, commonChunk);
+			return moduleFilterCount(module, count) && moduleFilterCondition(module, targetChunk);
 		}).map(entry => entry[0]);
 	}
 
-	getModulesSize(modules) {
+	calculateModuleSize(modules) {
 		return modules.reduce((count, module) => count + module.size(), 0);
 	}
 
-	removeModulesFromUsedChunksAndReturnUsedChunks(reallyUsedModules, usedChunks) {
+	extractModulesAndReturnAffectedChunks(reallyUsedModules, usedChunks) {
 		return reallyUsedModules.reduce((affectedChunksSet, module) => {
 			for(let chunk of usedChunks) {
 				// removeChunk returns true if the chunk was contained and succesfully removed
@@ -298,14 +304,14 @@ The available options are:
 		}, new Set());
 	}
 
-	connectModulesWithCommonChunk(chunk, modules) {
+	addExtractedModulesToTargetChunk(chunk, modules) {
 		for(let module of modules) {
 			chunk.addModule(module);
 			module.addChunk(chunk);
 		}
 	}
 
-	addCommonChunkAsParentOfAffectedChunks(usedChunks, commonChunk) {
+	makeTargetChunkParentOfAffectedChunks(usedChunks, commonChunk) {
 		for(let chunk of usedChunks) {
 			// set commonChunk as new sole parent
 			chunk.parents = [commonChunk];
@@ -318,7 +324,7 @@ The available options are:
 		}
 	}
 
-	connectChunkBlocksWithCommonChunk(chunks, commonChunk) {
+	moveExtractedChunkBlocksToTargetChunk(chunks, commonChunk) {
 		for(let chunk of chunks) {
 			// only for non initial chunks
 			// TODO: why?
@@ -331,7 +337,7 @@ The available options are:
 		}
 	}
 
-	getAsyncChunkOrigin(chunks) {
+	extractOriginsOfChunksWithExtractedModules(chunks) {
 		const origins = [];
 		for(let chunk of chunks) {
 			for(let origin of chunk.origins) {