Updated docs

client.go

@@ -44,25 +44,24 @@ import (
 	"time"
 )
 
-// Pilosa HTTP Client
-
-// Client queries the Pilosa server
+// Client is the HTTP client for Pilosa server.
 type Client struct {
 	cluster *Cluster
 	client  *http.Client
 }
 
-// DefaultClient creates the default client
+// DefaultClient creates a client with the default address and options.
 func DefaultClient() *Client {
 	return NewClientWithURI(DefaultURI())
 }
 
-// NewClientWithURI creates a client with the given address
+// NewClientWithURI creates a client with the given server address.
 func NewClientWithURI(uri *URI) *Client {
 	return NewClientWithCluster(NewClusterWithHost(uri), nil)
 }
 
-// NewClientWithCluster creates a client with the given cluster
+// NewClientWithCluster creates a client with the given cluster and options.
+// Pass nil for default options.
 func NewClientWithCluster(cluster *Cluster, options *ClientOptions) *Client {
 	if options == nil {
 		options = &ClientOptions{}
@@ -73,7 +72,8 @@ func NewClientWithCluster(cluster *Cluster, options *ClientOptions) *Client {
 	}
 }
 
-// Query sends a query to the Pilosa server with the given options
+// Query runs the given query against the server with the given options.
+// Pass nil for default options.
 func (c *Client) Query(query PQLQuery, options *QueryOptions) (*QueryResponse, error) {
 	if err := query.Error(); err != nil {
 		return nil, err
@@ -102,7 +102,7 @@ func (c *Client) Query(query PQLQuery, options *QueryOptions) (*QueryResponse, e
 	return queryResponse, nil
 }
 
-// CreateIndex creates an index with default options
+// CreateIndex creates an index on the server using the given Index struct.
 func (c *Client) CreateIndex(index *Index) error {
 	data := []byte(index.options.String())
 	path := fmt.Sprintf("/index/%s", index.name)
@@ -118,7 +118,7 @@ func (c *Client) CreateIndex(index *Index) error {
 
 }
 
-// CreateFrame creates a frame with default options
+// CreateFrame creates a frame on the server using the given Frame struct.
 func (c *Client) CreateFrame(frame *Frame) error {
 	data := []byte(frame.options.String())
 	path := fmt.Sprintf("/index/%s/frame/%s", frame.index.name, frame.name)
@@ -133,7 +133,7 @@ func (c *Client) CreateFrame(frame *Frame) error {
 
 }
 
-// EnsureIndex creates an index with default options if it doesn't already exist
+// EnsureIndex creates an index on the server if it does not exist.
 func (c *Client) EnsureIndex(index *Index) error {
 	err := c.CreateIndex(index)
 	if err == ErrorIndexExists {
@@ -142,7 +142,7 @@ func (c *Client) EnsureIndex(index *Index) error {
 	return err
 }
 
-// EnsureFrame creates a frame with default options if it doesn't already exists
+// EnsureFrame creates a frame on the server if it doesn't exists.
 func (c *Client) EnsureFrame(frame *Frame) error {
 	err := c.CreateFrame(frame)
 	if err == ErrorFrameExists {
@@ -151,22 +151,22 @@ func (c *Client) EnsureFrame(frame *Frame) error {
 	return err
 }
 
-// DeleteIndex deletes an index
+// DeleteIndex deletes an index on the server.
 func (c *Client) DeleteIndex(index *Index) error {
 	path := fmt.Sprintf("/index/%s", index.name)
 	_, _, err := c.httpRequest("DELETE", path, nil, noResponse)
 	return err
 
 }
 
-// DeleteFrame deletes a frame with default options
+// DeleteFrame deletes a frame on the server.
 func (c *Client) DeleteFrame(frame *Frame) error {
 	path := fmt.Sprintf("/index/%s/frame/%s", frame.index.name, frame.name)
 	_, _, err := c.httpRequest("DELETE", path, nil, noResponse)
 	return err
 }
 
-// Schema returns the indexes and frames of the server
+// Schema returns the indexes and frames on the server.
 func (c *Client) Schema() (*Schema, error) {
 	_, buf, err := c.httpRequest("GET", "/index", nil, errorCheckedResponse)
 	if err != nil {
@@ -300,12 +300,13 @@ func (options *ClientOptions) withDefaults() (updated *ClientOptions) {
 	return
 }
 
-// QueryOptions contains options that can be sent with a query
+// QueryOptions contains options to customize the Query function.
 type QueryOptions struct {
+	// Columns enables returning columns in the query response.
 	Columns bool
 }
 
-// Schema contains the index and frame metadata
+// Schema contains the index and frame metadata.
 type Schema struct {
 	Indexes []*IndexInfo `json:"indexes"`
 }

cluster.go

@@ -32,20 +32,20 @@
 
 package pilosa
 
-// Cluster is a simple ICluster implementation
+// Cluster contains hosts in a Pilosa cluster.
 type Cluster struct {
 	hosts     []*URI
 	nextIndex int
 }
 
-// DefaultCluster creates a Cluster with no addresses
+// DefaultCluster returns the default Cluster.
 func DefaultCluster() *Cluster {
 	return &Cluster{
 		hosts: make([]*URI, 0),
 	}
 }
 
-// NewClusterWithHost creates a Cluster with the given URIs
+// NewClusterWithHost returns a cluster with the given URIs.
 func NewClusterWithHost(hosts ...*URI) *Cluster {
 	cluster := DefaultCluster()
 	for _, host := range hosts {
@@ -54,12 +54,12 @@ func NewClusterWithHost(hosts ...*URI) *Cluster {
 	return cluster
 }
 
-// AddHost adds an address to the cluster
+// AddHost adds a host to the cluster.
 func (c *Cluster) AddHost(address *URI) {
 	c.hosts = append(c.hosts, address)
 }
 
-// Host returns the next address in the cluster
+// Host returns the next host in the cluster.
 func (c *Cluster) Host() *URI {
 	if len(c.hosts) == 0 {
 		return nil
@@ -70,7 +70,7 @@ func (c *Cluster) Host() *URI {
 	return uri
 }
 
-// RemoveHost removes an address from the cluster
+// RemoveHost removes the host with the given URI from the cluster.
 func (c *Cluster) RemoveHost(address *URI) {
 	for i, uri := range c.hosts {
 		if uri.Equals(address) {
@@ -80,7 +80,7 @@ func (c *Cluster) RemoveHost(address *URI) {
 	}
 }
 
-// Hosts returns all addresses in this cluster
+// Hosts returns all hosts in the cluster.
 func (c *Cluster) Hosts() []URI {
 	arr := make([]URI, 0, len(c.hosts))
 	for _, u := range c.hosts {

doc.go

@@ -0,0 +1,69 @@
+// Copyright 2017 Pilosa Corp.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions
+// are met:
+//
+// 1. Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//
+// 2. Redistributions in binary form must reproduce the above copyright
+// notice, this list of conditions and the following disclaimer in the
+// documentation and/or other materials provided with the distribution.
+//
+// 3. Neither the name of the copyright holder nor the names of its
+// contributors may be used to endorse or promote products derived
+// from this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+// CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+// DAMAGE.
+
+/*
+Package pilosa enables querying a Pilosa server.
+
+This client uses Pilosa's http+protobuf API.
+
+Usage:
+
+	import (
+		"fmt"
+		pilosa "github.com/pilosa/go-pilosa"
+	)
+
+	// Create a Client instance
+	client := pilosa.DefaultClient()
+
+	// Create an Index instance
+	index, err := NewIndex("repository", nil)
+	if err != nil {
+		panic(err)
+	}
+
+	stargazer, err := index.Frame("stargazer", nil)
+	if err != nil {
+		panic(err)
+	}
+
+	response, err := client.Query(stargazer.Bitmap(5), nil)
+	if err != nil {
+		panic(err)
+	}
+
+	// Act on the result
+	fmt.Println(response.Result())
+
+See also https://www.pilosa.com/docs/api-reference/ and https://www.pilosa.com/docs/query-language/.
+*/
+package pilosa

error.go

@@ -36,12 +36,12 @@ import (
 	"fmt"
 )
 
-// Error contains a Pilosa specific error
+// Error contains a Pilosa specific error.
 type Error struct {
 	Message string
 }
 
-// NewError creates a Pilosa error
+// NewError creates a Pilosa error.
 func NewError(message string) *Error {
 	return &Error{Message: message}
 }
@@ -50,7 +50,7 @@ func (e Error) Error() string {
 	return fmt.Sprintf("Error: %s", e.Message)
 }
 
-//
+// Predefined Pilosa errors.
 var (
 	ErrorEmptyCluster             = NewError("No usable addresses in the cluster")
 	ErrorIndexExists              = NewError("Index exists")