update docs for eval node (influxdata#846)

pipeline/eval.go

@@ -7,8 +7,8 @@ import (
 )
 
 // Evaluates expressions on each data point it receives.
-// A list of expressions may be provided and will be evaluated in the order they are given
-// and results of previous expressions are made available to later expressions.
+// A list of expressions may be provided and will be evaluated in the order they are given.
+// The results of expressions are available to later expressions in the list.
 // See the property EvalNode.As for details on how to reference the results.
 //
 // Example:
@@ -79,8 +79,8 @@ func (e *EvalNode) validate() error {
 }
 
 // List of names for each expression.
-// The expressions are evaluated in order and the result
-// of a previous expression will be available in later expressions
+// The expressions are evaluated in order. The result
+// of an expression may be referenced by later expressions
 // via the name provided.
 //
 // Example:
@@ -108,8 +108,8 @@ func (e *EvalNode) As(names ...string) *EvalNode {
 //            .as('value_bucket')
 //            .tags('value_bucket')
 //
-// The above example calculates a named bucket from the field `value`.
-// Then the `value_bucket` result is set as a tag 'value_bucket' on the point, instead of as a field.
+// The above example calculates an expression from the field `value`, casts it as a string, and names it `value_bucket`.
+// The `value_bucket` expression is then converted from a field on the point to a tag `value_bucket` on the point.
 //
 // Example:
 //    stream
@@ -118,9 +118,9 @@ func (e *EvalNode) As(names ...string) *EvalNode {
 //            .tags('value_bucket')
 //            .keep('value') // keep the original field `value` as well
 //
-// The above example calculates a named bucket from the field `value`.
-// Then the `value_bucket` result is set as a tag 'value_bucket' on the point, instead of as a field.
-// The field `value` is also preserved on the point because of the `keep` property.
+// The above example calculates an expression from the field `value`, casts it as a string, and names it `value_bucket`.
+// The `value_bucket` expression is then converted from a field on the point to a tag `value_bucket` on the point.
+// The `keep` property preserves the original field `value`.
 // Tags are always kept since creating a tag implies you want to keep it.
 //
 // tick:property
@@ -131,12 +131,13 @@ func (e *EvalNode) Tags(names ...string) *EvalNode {
 
 // If called the existing fields will be preserved in addition
 // to the new fields being set.
-// If not called then only new fields are preserved.
+// If not called then only new fields are preserved. (Tags are
+// always preserved regardless how `keep` is used.)
 //
-// Optionally intermediate values can be discarded
-// by passing a list of field names.
-// Only fields in the list will be kept.
-// If no list is given then all fields, new and old, are kept.
+// Optionally, intermediate values can be discarded
+// by passing a list of field names to be kept.
+// Only fields in the list will be retained, the rest will be discarded.
+// If no list is given then all fields are retained.
 //
 // Example:
 //    stream
@@ -145,9 +146,10 @@ func (e *EvalNode) Tags(names ...string) *EvalNode {
 //            .keep('value', 'inv_value2')
 //
 // In the above example the original field `value` is preserved.
-// In addition the new field `value2` is calculated and used in evaluating
-// `inv_value2` but is discarded before the point is sent on to children nodes.
-// The resulting point has only two fields `value` and `inv_value2`.
+// The new field `value2` is calculated and used in evaluating
+// `inv_value2` but is discarded before the point is sent on to child nodes.
+// The resulting point has only two fields: `value` and `inv_value2`.
+//
 // tick:property
 func (e *EvalNode) Keep(fields ...string) *EvalNode {
 	e.KeepFlag = true

pipeline/influxql.go

@@ -136,7 +136,7 @@ func (n *chainnode) Mean(field string) *InfluxQLNode {
 }
 
 // Compute the median of the data. Note, this method is not a selector,
-// if you want the median point use .percentile(field, 50.0).
+// if you want the median point use `.percentile(field, 50.0)`.
 func (n *chainnode) Median(field string) *InfluxQLNode {
 	i := newInfluxQLNode("median", field, n.Provides(), StreamEdge, ReduceCreater{
 		CreateFloatBulkReducer: func() (FloatBulkPointAggregator, influxql.FloatPointEmitter) {

pipeline/node.go

@@ -236,7 +236,7 @@ const intervalMarker = "INTERVAL"
 //
 // The `id` and `message` alert properties can be configured globally via the 'deadman' configuration section.
 //
-// Since the AlertNode is the last piece it can be further modified as normal.
+// Since the AlertNode is the last piece it can be further modified as usual.
 // Example:
 //    var data = stream
 //        |from()...
@@ -318,8 +318,8 @@ func (n *chainnode) Where(expression *ast.LambdaNode) *WhereNode {
 // Create an http output node that caches the most recent data it has received.
 // The cached data is available at the given endpoint.
 // The endpoint is the relative path from the API endpoint of the running task.
-// For example if the task endpoint is at "/api/v1/task/<task_name>" and endpoint is
-// "top10", then the data can be requested from "/api/v1/task/<task_name>/top10".
+// For example if the task endpoint is at `/api/v1/task/<task_name>` and endpoint is
+// `top10`, then the data can be requested from `/api/v1/task/<task_name>/top10`.
 func (n *chainnode) HttpOut(endpoint string) *HTTPOutNode {
 	h := newHTTPOutNode(n.provides, endpoint)
 	n.linkChild(h)
@@ -369,8 +369,8 @@ func (n *chainnode) Flatten() *FlattenNode {
 }
 
 // Create an eval node that will evaluate the given transformation function to each data point.
-//  A list of expressions may be provided and will be evaluated in the order they are given
-// and results of previous expressions are made available to later expressions.
+// A list of expressions may be provided and will be evaluated in the order they are given.
+// The results are available to later expressions.
 func (n *chainnode) Eval(expressions ...*ast.LambdaNode) *EvalNode {
 	e := newEvalNode(n.provides, expressions)
 	n.linkChild(e)