Merge pull request #1013 from plotly/js-better-docs

Enhance js docs: addTraces + moveTraces

Author: Kully

_posts/reference_pages/2016-06-03-plotly_js_function_ref.html

@@ -304,7 +304,8 @@ <h4 id="plotly-update"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-refe
 <h4 id="plotly-addtraces"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-reference/#plotlyaddtraces">Plotly.addTraces</a></h4>
 <em>This function has comparable performance to <a href="#plotlyreact"><code>Plotly.react</code></a> and is faster than redrawing the whole plot with <a href="#plotlynewplot"><code>Plotly.newPlot</code></a>.</em><br /><br />
 
-This allows you to add <b>new</b> traces to an existing <code>graphDiv</code> at any location in its data array.
+This allows you to add <b>new</b> traces to an existing <code>graphDiv</code> at any location in its <a href='#retrieving-data-layout'>data array</a>. Every <code>graphDiv</code> object has a <code>data</code> component which is an array of JSON blobs that each describe one trace. The full list of trace types can be found <a href="{{ BASE_URL }}/javascript/reference/">in the Full Reference</a>.
+
 
 <pre><code class="language-javascript hljs" data-lang="javascript">
 // add a single trace to an existing graphDiv
@@ -339,6 +340,8 @@ <h4 id="plotly-movetraces"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-
 <em>This function has comparable performance to <a href="#plotlyreact"><code>Plotly.react</code></a> and is faster than redrawing the whole plot with <a href="#plotlynewplot"><code>Plotly.newPlot</code></a>.</em><br /><br />
 This allows you to reorder traces in an existing <code>graphDiv</code>. This will change the ordering of the layering and the legend.
 
+All traces defined in <code>graphDiv</code> are ordered in an array. They are drawn one by one from first to last. Each time a new layer or trace is drawn to the canvas the new trace is drawn directly over the current canvas, replacing the colors of the traces and background. This algorithm to image stacking/drawing is known as the <a href='https://www.youtube.com/watch?v=oMgOR3PxmDU'>Painter's Algorithm</a>. As its name implies the Painter's Algorithm is typically the manner in which a painter paints a landscape, starting from objects with the most perspective depth and progressively moving forward and layering over the background objects.
+
 <pre><code class="language-javascript hljs" data-lang="javascript">
 // move the first trace (at index 0) the the end of the data array
 Plotly.moveTraces(graphDiv, 0);
@@ -427,4 +430,3 @@ <h4 id="plotly-downloadImage"><a href="{{ BASE_URL }}/javascript/plotlyjs-functi
 <h4 id="plotly-events"><a href="{{ BASE_URL }}/javascript/plotlyjs-function-reference/#using-events">Using events</a></h4>
 
 Plots emit events prefixed with <code>plotly_</code> when clicked or hovered over, and event handlers can be bound to events using the <code>on</code> method that is exposed by the plot div object. For more information and examples of how to use Plotly events see: <a href="https://plot.ly/javascript/plotlyjs-events/">https://plot.ly/javascript/plotlyjs-events/</a>.
-