From 91064cac5c3f7ed14741c96641f9a7436a19c33b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89tienne=20T=C3=A9treault-Pinard?= <etienne@plot.ly>
Date: Thu, 9 Aug 2018 14:30:03 -0400
Subject: [PATCH] add :books: about axes in polar subplots

---
 src/plots/polar/polar.js | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/src/plots/polar/polar.js b/src/plots/polar/polar.js
index 01f838c978a..8cc57c66343 100644
--- a/src/plots/polar/polar.js
+++ b/src/plots/polar/polar.js
@@ -156,6 +156,32 @@ proto.updateLayers = function(fullLayout, polarLayout) {
     join.order();
 };
 
+/* Polar subplots juggle with 6 'axis objects' (!), these are:
+ *
+ * - polarLayout.radialaxis (aka radialLayout in this file):
+ * - polarLayout.angularaxis (aka angularLayout in this file):
+ *   used for data -> calcdata conversions (aka d2c) during the calc step
+ *
+ * - this.radialAxis
+ *   extends polarLayout.radialaxis, adds mocked 'domain' and
+ *   few other keys in order to reuse Cartesian doAutoRange and doTicksSingle,
+ *   used for calcdata -> geometric conversions (aka c2g) during the plot step
+ *   + setGeometry setups ax.c2g for given ax.range
+ *   + setScale setups ax._m,ax._b for given ax.range
+ *
+ * - this.angularAxis
+ *   extends polarLayout.angularaxis, adds mocked 'range' and 'domain' and
+ *   a few other keys in order to reuse Cartesian doTicksSingle,
+ *   used for calcdata -> geometric conversions (aka c2g) during the plot step
+ *   + setGeometry setups ax.c2g given ax.rotation, ax.direction & ax._categories,
+ *                 and mocks ax.range
+ *   + setScale setups ax._m,ax._b with that mocked ax.range
+ *
+ * - this.xaxis
+ * - this.yaxis
+ *   setup so that polar traces can reuse plot methods of Cartesian traces
+ *   which mostly rely on 2pixel methods (e.g ax.c2p)
+ */
 proto.updateLayout = function(fullLayout, polarLayout) {
     var _this = this;
     var layers = _this.layers;