diff --git a/src/shaders/index.js b/src/shaders/index.js
index 84d4d0d0b4c..3af8f6ae10f 100644
--- a/src/shaders/index.js
+++ b/src/shaders/index.js
@@ -1,5 +1,9 @@
+// This file is intended for use in the GL-JS test suite
+// It provides the shaders entry point for Node (tests and GL Native)
+// In a browser environment, this file is replaced with ./src/shaders/shaders.js
+// when Rollup builds the main bundle.
+// See https://github.com/mapbox/mapbox-gl-js/blob/master/package.json#L104-L108
 
-// Shaders entry point for Node (tests and GL Native)
 /* eslint-disable import/unambiguous, import/no-commonjs, flowtype/require-valid-file-annotation, no-global-assign */
 
 const fs = require('fs');
diff --git a/src/util/web_worker.js b/src/util/web_worker.js
index 6462e4cdb87..33b9d3489e1 100644
--- a/src/util/web_worker.js
+++ b/src/util/web_worker.js
@@ -1,5 +1,11 @@
 // @flow
 
+// This file is intended for use in the GL-JS test suite
+// It implements a MessageBus main thread interface for use in Node environments
+// In a browser environment, this file is replaced with ./src/util/browser/web_worker.js
+// when Rollup builds the main bundle.
+// See https://github.com/mapbox/mapbox-gl-js/blob/master/package.json#L104-L108
+
 import Worker from '../source/worker';
 
 import type {WorkerSource} from '../source/worker_source';
diff --git a/src/util/window.js b/src/util/window.js
index 45f07923940..7019c9650c9 100644
--- a/src/util/window.js
+++ b/src/util/window.js
@@ -1,5 +1,11 @@
 // @flow
 
+// This file is intended for use in the GL-JS test suite
+// It implements a JSDOM window object for use in Node environments
+// In a browser environment, this file is replaced with ./src/util/browser/window.js
+// when Rollup builds the main bundle
+// See https://github.com/mapbox/mapbox-gl-js/blob/master/package.json#L104-L108
+
 import jsdom from 'jsdom';
 
 import gl from 'gl';