Add comments explaining bundling strategy

build/rollup_plugins.js

@@ -1,3 +1,4 @@
+
 import flowRemoveTypes from 'flow-remove-types';
 import buble from 'rollup-plugin-buble';
 import resolve from 'rollup-plugin-node-resolve';
@@ -12,9 +13,12 @@ import minifyStyleSpec from './rollup_plugin_minify_style_spec';
 
 const production = process.env.BUILD === 'production';
 
+// Common set of plugins/transformations shared across different rollup
+// builds (main mapboxgl bundle, style-spec package, benchmarks bundle)
+
 export const plugins = () => [
     sourcemaps(),
-    flow(), // setting {pretty: true} works around https://github.com/leebyron/rollup-plugin-flow/issues/5
+    flow(),
     minifyStyleSpec(),
     json(),
     buble({transforms: {dangerousForOf: true}, objectAssign: "Object.assign"}),

rollup.config.js

@@ -5,16 +5,26 @@ const production = process.env.BUILD === 'production';
 const outputFile = production ? 'dist/mapbox-gl.js' : 'dist/mapbox-gl-dev.js';
 
 const config = [{
+    // First, use code splitting to bundle GL JS into three "chunks":
+    // - rollup/build/index.js: the main module, plus all its dependencies not shared by the worker module
+    // - rollup/build/worker.js: the worker module, plus all dependencies not shared by the main module
+    // - rollup/build/chunk1.js: the set of modules that are dependencies of both the main module and the worker module
+    //
+    // This is also where we do all of our source transformations: removing
+    // flow annotations, transpiling ES6 features using buble, inlining shader
+    // sources as strings, etc.
     input: ['src/index.js', 'src/source/worker.js'],
     output: {
-        name: 'mapboxgl',
         dir: 'rollup/build',
         format: 'amd',
         sourcemap: 'inline'
     },
     experimentalCodeSplitting: true,
     plugins: plugins()
 }, {
+    // Next, bundle together the three "chunks" produced in the previous pass
+    // into a single, final bundle. See 'intro:' below and rollup/mapboxgl.js
+    // for details.
     input: 'rollup/mapboxgl.js',
     output: {
         name: 'mapboxgl',
@@ -25,21 +35,22 @@ const config = [{
     plugins: [sourcemaps()],
     intro: `
 let shared, worker, mapboxgl;
-function define(_, module) {
+// define gets called three times: one for each chunk. we rely on the order
+// they're imported to know which is which
+function define(_, chunk) {
 if (!shared) {
-    shared = module;
+    shared = chunk;
 } else if (!worker) {
-    worker = module;
+    worker = chunk;
 } else {
-    const workerBundleString = 'const sharedModule = {}; (' + shared + ')(sharedModule); (' + worker + ')(sharedModule);'
+    const workerBundleString = 'const sharedChunk = {}; (' + shared + ')(sharedChunk); (' + worker + ')(sharedChunk);'
 
-    const sharedModule = {};
-    shared(sharedModule);
-    mapboxgl = module(sharedModule);
+    const sharedChunk = {};
+    shared(sharedChunk);
+    mapboxgl = chunk(sharedChunk);
     mapboxgl.workerUrl = window.URL.createObjectURL(new Blob([workerBundleString], { type: 'text/javascript' }));
 }
-}
-`
+}`
 }];
 
 export default config

rollup/mapboxgl.js

@@ -1,5 +1,47 @@
+//
+// Our custom intro provides a specialized "define()" function, called by the
+// AMD modules below, that sets up the worker blob URL and then executes the
+// main module, storing its exported value as 'mapboxgl'
+
+// The three "chunks" imported here are produced by a first Rollup pass,
+// which outputs them as AMD modules.
+
+// Shared dependencies, i.e.:
+/*
+define(['exports'], function (exports) {
+    // Code for all common dependencies
+    // Each module's exports are attached attached to 'exports' (with
+    // names rewritten to avoid collisions, etc.)
+})
+*/
 import './build/chunk1';
+
+// Worker and its unique dependencies, i.e.:
+/*
+define(['./chunk1.js'], function (__chunk1__js) {
+    //  Code for worker script and its unique dependencies.
+    //  Expects the output of 'chunk1' module to be passed in as an argument,
+    //  since all references to common deps look like, e.g.,
+    //  __chunk1__js.shapeText().
+});
+*/
+// When this wrapper function is passed to our custom define() above,
+// it gets stringified, together with the chunk1 wrapper (using
+// Function.toString()), and the resulting string of code is made into a
+// Blob URL that gets used by the main module to create the web workers.
 import './build/worker';
+
+// Main module and its unique dependencies
+/*
+define(['./chunk1.js'], function (__chunk1__js) {
+    //  Code for main GL JS module and its unique dependencies.
+    //  Expects the output of 'chunk1' module to be passed in as an argument,
+    //  since all references to common deps look like, e.g.,
+    //  __chunk1__js.shapeText().
+    //
+    //  Returns the actual mapboxgl (i.e. src/index.js)
+});
+*/
 import './build/index';
 
 export default mapboxgl;