Update godoc for the client packages

client/influxdb.go

@@ -1,3 +1,5 @@
+// Package client implements a now-deprecated client for InfluxDB;
+// use github.com/influxdata/influxdb/client/v2 instead.
 package client // import "github.com/influxdata/influxdb/client"
 
 import (

client/v2/client.go

@@ -1,3 +1,4 @@
+// Package client (v2) is the current official Go client for InfluxDB.
 package client // import "github.com/influxdata/influxdb/client/v2"
 
 import (
@@ -14,26 +15,26 @@ import (
 	"github.com/influxdata/influxdb/models"
 )
 
-// HTTPConfig is the config data needed to create an HTTP Client
+// HTTPConfig is the config data needed to create an HTTP Client.
 type HTTPConfig struct {
 	// Addr should be of the form "http://host:port"
 	// or "http://[ipv6-host%zone]:port".
 	Addr string
 
-	// Username is the influxdb username, optional
+	// Username is the influxdb username, optional.
 	Username string
 
-	// Password is the influxdb password, optional
+	// Password is the influxdb password, optional.
 	Password string
 
-	// UserAgent is the http User Agent, defaults to "InfluxDBClient"
+	// UserAgent is the http User Agent, defaults to "InfluxDBClient".
 	UserAgent string
 
-	// Timeout for influxdb writes, defaults to no timeout
+	// Timeout for influxdb writes, defaults to no timeout.
 	Timeout time.Duration
 
 	// InsecureSkipVerify gets passed to the http client, if true, it will
-	// skip https certificate verification. Defaults to false
+	// skip https certificate verification. Defaults to false.
 	InsecureSkipVerify bool
 
 	// TLSConfig allows the user to set their own TLS config for the HTTP
@@ -41,25 +42,25 @@ type HTTPConfig struct {
 	TLSConfig *tls.Config
 }
 
-// BatchPointsConfig is the config data needed to create an instance of the BatchPoints struct
+// BatchPointsConfig is the config data needed to create an instance of the BatchPoints struct.
 type BatchPointsConfig struct {
-	// Precision is the write precision of the points, defaults to "ns"
+	// Precision is the write precision of the points, defaults to "ns".
 	Precision string
 
-	// Database is the database to write points to
+	// Database is the database to write points to.
 	Database string
 
-	// RetentionPolicy is the retention policy of the points
+	// RetentionPolicy is the retention policy of the points.
 	RetentionPolicy string
 
-	// Write consistency is the number of servers required to confirm write
+	// Write consistency is the number of servers required to confirm write.
 	WriteConsistency string
 }
 
-// Client is a client interface for writing & querying the database
+// Client is a client interface for writing & querying the database.
 type Client interface {
 	// Ping checks that status of cluster, and will always return 0 time and no
-	// error for UDP clients
+	// error for UDP clients.
 	Ping(timeout time.Duration) (time.Duration, string, error)
 
 	// Write takes a BatchPoints object and writes all Points to InfluxDB.
@@ -177,31 +178,31 @@ type client struct {
 // InfluxDB together. BatchPoints is NOT thread-safe, you must create a separate
 // batch for each goroutine.
 type BatchPoints interface {
-	// AddPoint adds the given point to the Batch of points
+	// AddPoint adds the given point to the Batch of points.
 	AddPoint(p *Point)
-	// AddPoints adds the given points to the Batch of points
+	// AddPoints adds the given points to the Batch of points.
 	AddPoints(ps []*Point)
-	// Points lists the points in the Batch
+	// Points lists the points in the Batch.
 	Points() []*Point
 
-	// Precision returns the currently set precision of this Batch
+	// Precision returns the currently set precision of this Batch.
 	Precision() string
 	// SetPrecision sets the precision of this batch.
 	SetPrecision(s string) error
 
-	// Database returns the currently set database of this Batch
+	// Database returns the currently set database of this Batch.
 	Database() string
-	// SetDatabase sets the database of this Batch
+	// SetDatabase sets the database of this Batch.
 	SetDatabase(s string)
 
-	// WriteConsistency returns the currently set write consistency of this Batch
+	// WriteConsistency returns the currently set write consistency of this Batch.
 	WriteConsistency() string
-	// SetWriteConsistency sets the write consistency of this Batch
+	// SetWriteConsistency sets the write consistency of this Batch.
 	SetWriteConsistency(s string)
 
-	// RetentionPolicy returns the currently set retention policy of this Batch
+	// RetentionPolicy returns the currently set retention policy of this Batch.
 	RetentionPolicy() string
-	// SetRetentionPolicy sets the retention policy of this Batch
+	// SetRetentionPolicy sets the retention policy of this Batch.
 	SetRetentionPolicy(s string)
 }
 
@@ -278,7 +279,7 @@ func (bp *batchpoints) SetRetentionPolicy(rp string) {
 	bp.retentionPolicy = rp
 }
 
-// Point represents a single data point
+// Point represents a single data point.
 type Point struct {
 	pt models.Point
 }
@@ -307,37 +308,38 @@ func NewPoint(
 	}, nil
 }
 
-// String returns a line-protocol string of the Point
+// String returns a line-protocol string of the Point.
 func (p *Point) String() string {
 	return p.pt.String()
 }
 
-// PrecisionString returns a line-protocol string of the Point, at precision
+// PrecisionString returns a line-protocol string of the Point,
+// with the timestamp formatted for the given precision.
 func (p *Point) PrecisionString(precison string) string {
 	return p.pt.PrecisionString(precison)
 }
 
-// Name returns the measurement name of the point
+// Name returns the measurement name of the point.
 func (p *Point) Name() string {
 	return p.pt.Name()
 }
 
-// Tags returns the tags associated with the point
+// Tags returns the tags associated with the point.
 func (p *Point) Tags() map[string]string {
 	return p.pt.Tags().Map()
 }
 
-// Time return the timestamp for the point
+// Time return the timestamp for the point.
 func (p *Point) Time() time.Time {
 	return p.pt.Time()
 }
 
-// UnixNano returns the unix nano time of the point
+// UnixNano returns timestamp of the point in nanoseconds since Unix epoch.
 func (p *Point) UnixNano() int64 {
 	return p.pt.UnixNano()
 }
 
-// Fields returns the fields for the point
+// Fields returns the fields for the point.
 func (p *Point) Fields() map[string]interface{} {
 	return p.pt.Fields()
 }
@@ -398,7 +400,7 @@ func (c *client) Write(bp BatchPoints) error {
 	return nil
 }
 
-// Query defines a query to send to the server
+// Query defines a query to send to the server.
 type Query struct {
 	Command    string
 	Database   string
@@ -406,9 +408,8 @@ type Query struct {
 	Parameters map[string]interface{}
 }
 
-// NewQuery returns a query object
+// NewQuery returns a query object.
-// database and precision strings can be empty strings if they are not needed
+// The database and precision arguments can be empty strings if they are not needed for the query.
-// for the query.
 func NewQuery(command, database, precision string) Query {
 	return Query{
 		Command:    command,
@@ -418,11 +419,9 @@ func NewQuery(command, database, precision string) Query {
 	}
 }
 
-// NewQueryWithParameters returns a query object
+// NewQueryWithParameters returns a query object.
-// database and precision strings can be empty strings if they are not needed
+// The database and precision arguments can be empty strings if they are not needed for the query.
-// for the query.
+// parameters is a map of the parameter names used in the command to their values.
-// parameters is a map of the parameter names used in the command to their
-// values.
 func NewQueryWithParameters(command, database, precision string, parameters map[string]interface{}) Query {
 	return Query{
 		Command:    command,
@@ -439,7 +438,7 @@ type Response struct {
 }
 
 // Error returns the first error from any statement.
-// Returns nil if no errors occurred on any statements.
+// It returns nil if no errors occurred on any statements.
 func (r *Response) Error() error {
 	if r.Err != "" {
 		return fmt.Errorf(r.Err)
@@ -465,7 +464,7 @@ type Result struct {
 	Err      string `json:"error,omitempty"`
 }
 
-// Query sends a command to the server and returns the Response
+// Query sends a command to the server and returns the Response.
 func (c *client) Query(q Query) (*Response, error) {
 	u := c.url
 	u.Path = "query"

client/v2/udp.go

@@ -13,7 +13,7 @@ const (
 	UDPPayloadSize = 512
 )
 
-// UDPConfig is the config data needed to create a UDP Client
+// UDPConfig is the config data needed to create a UDP Client.
 type UDPConfig struct {
 	// Addr should be of the form "host:port"
 	// or "[ipv6-host%zone]:port".

influxdb.go

@@ -1 +1,6 @@
+// Package influxdb is the root package of InfluxDB,
+// the scalable datastore for metrics, events, and real-time analytics.
+//
+// If you're looking for the Go HTTP client for InfluxDB,
+// see package github.com/influxdata/influxdb/client/v2.
 package influxdb // import "github.com/influxdata/influxdb"