From 0daa2cf574e71bd3cac7efe5dfa1beaa77cac004 Mon Sep 17 00:00:00 2001
From: Peter Robins <github@peterrobins.co.uk>
Date: Sun, 8 May 2016 09:50:22 +0000
Subject: [PATCH] Document typedef move

---
 changelog/v3.16.0.md | 12 ++++++++++++
 src/ol/typedefs.js   | 28 +++++++++++++++++++++++-----
 2 files changed, 35 insertions(+), 5 deletions(-)
 create mode 100644 changelog/v3.16.0.md

diff --git a/changelog/v3.16.0.md b/changelog/v3.16.0.md
new file mode 100644
index 0000000000..49e785b15f
--- /dev/null
+++ b/changelog/v3.16.0.md
@@ -0,0 +1,12 @@
+# v3.16.0
+
+## Summary
+
+
+## Upgrade notes
+
+### v3.16.0
+
+#### Move of typedefs out of code and into separate file
+
+This change should not affect the great majority of application developers, but it's possible there are edge cases when compiling application code together with the library which cause compiler errors or warnings. In this case, please raise a GitHub issue. `goog.require`s for typedefs should not be necessary.
diff --git a/src/ol/typedefs.js b/src/ol/typedefs.js
index 98cec9740c..8a966e6891 100644
--- a/src/ol/typedefs.js
+++ b/src/ol/typedefs.js
@@ -1,10 +1,28 @@
 /**
- * File for all top-level (in the `ol` namespace) typedefs used by the compiler,
- * and referenced by JSDoc.
+ * File for all typedefs used by the compiler, and referenced by JSDoc.
  *
- * goog.provides are needed for 2 cases:
- * - the 1st two are to prevent compiler errors
- * - the others are to prevent 'defined before its owner' warnings
+ * These look like vars (or var properties), but in fact are simply identifiers
+ * for the Closure compiler. Originally they were included in the appropriate
+ * namespace file, but with the move away from Closure namespaces and towards
+ * self-contained standard modules are now all in this file, with two exceptions.
+ * Unlike the other type definitions - enums and constructor functions - they
+ * are not code and so are not imported or exported. They are only referred to
+ * in type-defining comments used by the Closure compiler, and so should not
+ * appear in module code.
+ *
+ * The 2 exceptions are the WFS typedefs which are in a sub-sub-namespace and
+ * are API. These have been put in their own separate file.
+ *
+ * When the code is converted to ES6 modules, the namespace structure will
+ * disappear, and these typedefs will have to be renamed accordingly, but the
+ * namespace structure is maintained for the present for backwards compatibility.
+ *
+ * In principle, typedefs should not have a `goog.provide` nor should files which
+ * refer to a typedef in comments need a `goog.require`. However, goog.provides
+ * are needed for 2 cases, both to prevent compiler errors/warnings:
+ * - the 1st two for specific errors
+ * - each sub-namespace needs at least one so the namespace is created when not
+ *   used in the code, as when application code is compiled with the library.
  */
 goog.provide('ol.Extent');
 goog.provide('ol.events.EventTargetLike');