From 2e1957c42c23fe23d7573edbc7d52a7873b83a78 Mon Sep 17 00:00:00 2001
From: Peter Robins <github@peterrobins.co.uk>
Date: Wed, 2 Jul 2014 06:43:20 -0400
Subject: [PATCH] Improve docs for define tag

---
 src/ol/ol.js    | 28 ++++++++++++++++++++++------
 tasks/readme.md |  1 +
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/src/ol/ol.js b/src/ol/ol.js
index c2057ed4c4..52ac500cdd 100644
--- a/src/ol/ol.js
+++ b/src/ol/ol.js
@@ -3,6 +3,13 @@ goog.require('goog.userAgent');
 goog.provide('ol');
 
 
+/**
+ * Constants defined with the define tag cannot be changed in application
+ * code, but can be set at compile time.
+ * Some reduce the size of the build in advanced compile mode.
+ */
+
+
 /**
  * @define {boolean} Assume touch.  Default is `false`.
  */
@@ -72,21 +79,26 @@ ol.DRAG_BOX_HYSTERESIS_PIXELS = 8;
 
 
 /**
- * @define {boolean} Enable the Canvas renderer.  Default is `true`.
+ * @define {boolean} Enable the Canvas renderer.  Default is `true`. Setting
+ *     this to false at compile time in advanced mode removes all code
+ *     supporting the Canvas renderer from the build.
  */
 ol.ENABLE_CANVAS = true;
 
 
 /**
  * @define {boolean} Enable the DOM renderer (used as a fallback where Canvas is
- *     not available).  Default is `true`.
+ *     not available).  Default is `true`. Setting this to false at compile time
+ *     in advanced mode removes all code supporting the DOM renderer from the
+ *     build.
  */
 ol.ENABLE_DOM = true;
 
 
 /**
  * @define {boolean} Enable rendering of ol.layer.Image based layers.  Default
- *     is `true`.
+ *     is `true`. Setting this to false at compile time in advanced mode removes
+ *     all code supporting Image layers from the build.
  */
 ol.ENABLE_IMAGE = true;
 
@@ -108,20 +120,24 @@ ol.ENABLE_PROJ4JS = true;
 
 /**
  * @define {boolean} Enable rendering of ol.layer.Tile based layers.  Default is
- *     `true`.
+ *     `true`. Setting this to false at compile time in advanced mode removes
+ *     all code supporting Tile layers from the build.
  */
 ol.ENABLE_TILE = true;
 
 
 /**
  * @define {boolean} Enable rendering of ol.layer.Vector based layers.  Default
- *     is `true`.
+ *     is `true`. Setting this to false at compile time in advanced mode removes
+ *     all code supporting Vector layers from the build.
  */
 ol.ENABLE_VECTOR = true;
 
 
 /**
- * @define {boolean} Enable the WebGL renderer.  Default is `true`.
+ * @define {boolean} Enable the WebGL renderer.  Default is `true`. Setting
+ *     this to false at compile time in advanced mode removes all code
+ *     supporting the WebGL renderer from the build.
  */
 ol.ENABLE_WEBGL = true;
 
diff --git a/tasks/readme.md b/tasks/readme.md
index abb4c79a32..2e6dcb99f9 100644
--- a/tasks/readme.md
+++ b/tasks/readme.md
@@ -82,6 +82,7 @@ To export the `ol` symbol to somewhere other than the global namespace, a `names
 }
 ```
 
+The `defines` section of `build.json` above lists common settings for the Closure library in production code. The OL3 library also defines constants that can be set in this section at compile time. These are all defined in the `ol.js` source file; see the comments in this file to see what effect setting these would have. Some of them can reduce the size of the build in advanced mode.
 
 ## `generate-exports.js`