doc: add comments about non-trivial logic in ohlc / candlestick

Author: etpinard

src/components/legend/draw.js

@@ -377,6 +377,7 @@ function drawTexts(g, gd) {
                     astr;
 
                 // N.B. this block isn't super clean,
+                // is unfortunately untested at the moment,
                 // and only works for for 'ohlc' and 'candlestick',
                 // but should be generalized for other one-to-many transforms
                 if(['ohlc', 'candlestick'].indexOf(fullInput.type) !== -1) {

src/lib/coerce.js

@@ -457,7 +457,12 @@ exports.findArrayAttributes = function(trace) {
 
     exports.crawl(trace._module.attributes, callback);
 
-    // TODO add comment
+    // Look into the fullInput module attributes for array attributes
+    // to make sure that 'custom' array attributes are detected.
+    //
+    // At the moment, we need this block to make sure that
+    // ohlc and candlestick 'open', 'high', 'low', 'close' can be
+    // used with filter ang groupby transforms.
     if(trace._fullInput) {
         exports.crawl(trace._fullInput._module.attributes, callback);
 

src/traces/candlestick/index.js

@@ -18,7 +18,17 @@ module.exports = {
     categories: ['cartesian', 'showLegend'],
     meta: {
         description: [
-            // ...
+            'The candlestick is a style of financial chart describing',
+            'open, high, low and close for a given `x` coordinate (most likely time).',
+
+            'The boxes represent the spread between the `open` and `close` values and',
+            'the lines represent the spread between the `low` and `high` values',
+
+            'Sample points where the close value is higher (lower) then the open',
+            'value are called increasing (decreasing).',
+
+            'By default, increasing candles are drawn in green whereas',
+            'decreasing are drawn in red.'
         ].join(' ')
     },
 

src/traces/ohlc/attributes.js

@@ -93,7 +93,7 @@ module.exports = {
             'Sets hover text elements associated with each sample point.',
             'If a single string, the same string appears over',
             'all the data points.',
-            'If an array of string, the items are mapped in order to the',
+            'If an array of string, the items are mapped in order to',
             'this trace\'s sample points.'
         ].join(' ')
     },

src/traces/ohlc/helpers.js

@@ -11,7 +11,15 @@
 
 var Lib = require('../../lib');
 
-// TODO add comment
+// This routine gets called during the trace supply-defaults step.
+//
+// This is a hacky way to make 'ohlc' and 'candlestick' trace types
+// go through the transform machinery.
+//
+// Note that, we must mutate user data (here traceIn) as opposed
+// to full data (here traceOut) as - at the moment - transform
+// defaults (which are called after trace defaults) start
+// from a clear transforms container.
 exports.pushDummyTransformOpts = function(traceIn, traceOut) {
     var transformOpts = {
 
@@ -25,6 +33,8 @@ exports.pushDummyTransformOpts = function(traceIn, traceOut) {
     if(Array.isArray(traceIn.transforms)) {
         var transformsIn = traceIn.transforms;
 
+        // remove all ephemeral transforms,
+        // before adding dummy transform
         for(var i = 0; i < transformsIn.length; i++) {
             if(transformsIn[i]._ephemeral) transformsIn.splice(i, 1);
         }
@@ -36,18 +46,28 @@ exports.pushDummyTransformOpts = function(traceIn, traceOut) {
     }
 };
 
-// TODO add comment
+// This routine gets called during the transform supply-defaults step,
+// but only has an effect (because of the if-statements) during the
+// second round of transform defaults done on generated traces.
+//
+// This is a hacky way to pass 'ohlc' and 'candlestick' attributes
+// (found the transform container via exports.makeTransform)
+// to the traceOut container such that they can be compatible with
+// filter and groupby transforms.
 exports.copyOHLC = function(container, traceOut) {
     if(container.open) traceOut.open = container.open;
     if(container.high) traceOut.high = container.high;
     if(container.low) traceOut.low = container.low;
     if(container.close) traceOut.close = container.close;
 };
 
-// We need to track which direction ('increasing' or 'decreasing')
+// This routine gets called during the applyTransform step.
+//
+// We need to track trace attributes and which direction
+// ('increasing' or 'decreasing')
 // the generated correspond to for the calcTransform step.
 //
-// To make sure that direction reaches the calcTransform,
+// To make sure that the attributes reach the calcTransform,
 // store it in the transform opts object.
 exports.makeTransform = function(traceIn, state, direction) {
     var out = Lib.extendFlat([], traceIn.transforms);
@@ -56,7 +76,7 @@ exports.makeTransform = function(traceIn, state, direction) {
         type: traceIn.type,
         direction: direction,
 
-        // ...
+        // these are copied to traceOut during exports.copyOHLC
         open: traceIn.open,
         high: traceIn.high,
         low: traceIn.low,

src/traces/ohlc/index.js

@@ -18,7 +18,17 @@ module.exports = {
     categories: ['cartesian', 'showLegend'],
     meta: {
         description: [
-            // ...
+            'The ohlc (short for Open-High-Low-Close) is a style of financial chart describing',
+            'open, high, low and close for a given `x` coordinate (most likely time).',
+
+            'The tip of the lines represent the `low` and `high` values and',
+            'the horizontal segments represent the `open` and `close` values.',
+
+            'Sample points where the close value is higher (lower) then the open',
+            'value are called increasing (decreasing).',
+
+            'By default, increasing candles are drawn in green whereas',
+            'decreasing are drawn in red.'
         ].join(' ')
     },
 

test/jasmine/tests/finance_test.js

@@ -685,9 +685,4 @@ describe('finance charts updates:', function() {
             done();
         });
     });
-
-    it('legend *editable: true* interactions should work', function(done) {
-
-        done();
-    });
 });