Merge pull request #32 from deta/docs

Update Docs

deta/deta.go

@@ -1,61 +1,19 @@
-/*
-Package deta is the official Deta SDK for Go
-
-Example:
-	package main
-
-	import (
-		"fmt"
-
-		"github.com/deta/deta-go/deta"
-		"github.com/deta/deta-go/service/base"
-	)
-
-	type User struct {
-		Key      string `json:"key"` // json struct tag key to denote the key
-		Username string `json:"username"`
-		Email    string `json:"email"`
-	}
-
-	func main() {
-		d, err := deta.New(deta.WithProjectKey("project_key"))
-		if err != nil {
-			fmt.Println("failed to init new Deta instance:", err)
-			return
-		}
-
-		db := base.New(d, "users")
-
-		u := &User{
-			Key:      "abasd",
-			Username: "jimmy",
-			Email:    "[email protected]",
-		}
-		key, err := db.Put(u)
-		if err != nil {
-			fmt.Println("failed to put item:", err)
-			return
-		}
-		fmt.Println("successfully put item with key", key)
-	}
-
-More examples on https://docs.deta.sh/docs/base/sdk
-*/
 package deta
 
 import (
 	"os"
 	"strings"
 )
 
-// Deta is a top-level deta service instance
+// Deta is the top-level Deta service instance
 type Deta struct {
-	ProjectKey string
+	ProjectKey string // deta project key
 }
 
+// ConfigOption is a functional config option for Deta
 type ConfigOption func(*Deta)
 
-// Func returns a function that updates the ProjectKey
+// WithProjectKey config option for setting the project key for Deta
 func WithProjectKey(projectKey string) ConfigOption {
 	return func(d *Deta) {
 		d.ProjectKey = projectKey

deta/doc.go

@@ -0,0 +1,24 @@
+/*
+Package deta is the core Deta SDK package.
+
+Configuring credentials
+
+You will require you project key when using the Deta SDK.
+
+By default, the SDK looks for the environment variable DETA_PROJECT_KEY for the project key.
+
+	// Create a new Deta instance taking the project key from the environment by default
+	d, err := deta.New()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to create new deta instance: %v\n", err)
+	}
+
+You can use the WithProjectKey option when creating a Deta instance to provide the project key explicitly.
+
+	// Create a new Deta instance with explicit project key
+	d, err := deta.New(deta.WithProjectKey("project_key"))
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "failed to create new deta instance: %v\n", err)
+	}
+*/
+package deta

doc.go

@@ -0,0 +1,14 @@
+/*
+Package sdk is the official Deta SDK for Go.
+
+SDK Packages
+
+The SDK constitutes of two main components, the core package and service packages.
+
+deta - The core SDK package, provides shared functionalities to the service packages. All the errors are also exported from this package.
+
+service - The service packages, the services supported by the SDK.
+	base - Deta Base service package
+	drive - Deta Drive service package
+*/
+package sdk

internal/client/client.go

@@ -1,38 +1,35 @@
+// Package client provides an internal Deta client
+//
+// This is an internal package and should not be used by SDK users.
 package client
 
 import (
 	"bytes"
 	"encoding/json"
-	"errors"
 	"fmt"
 	"io"
 	"io/ioutil"
 	"net/http"
 	"strings"
-	"github.com/deta/deta-go/deta"
-)
 
-var (
-	// internal error
-	// invalid auth type
-	errInvalidAuthType = errors.New("invalid auth type")
+	"github.com/deta/deta-go/deta"
 )
 
-// auth info for requests
+// AuthInfo for requests
 type AuthInfo struct {
 	AuthType    string // auth type
 	HeaderKey   string // header key
 	HeaderValue string // header value
 }
 
-// client that talks with deta apis
+// DetaClient talks to Deta APIs
 type DetaClient struct {
 	RootEndpoint string
 	Client       *http.Client
 	AuthInfo     *AuthInfo
 }
 
-// returns a pointer to a new deta client
+// NewDetaClient returns a pointer to a new deta client
 func NewDetaClient(rootEndpoint string, ai *AuthInfo) *DetaClient {
 	// only api keys auth for now
 	/*
@@ -78,7 +75,7 @@ func (c *DetaClient) errorRespToErr(e *errorResp) error {
 	}
 }
 
-// input to request method
+// RequestInput to Request method
 type RequestInput struct {
 	Path             string
 	Method           string
@@ -90,7 +87,7 @@ type RequestInput struct {
 	ReturnReadCloser bool
 }
 
-// output of request function
+// RequestOutput of Request method
 type RequestOutput struct {
 	Status         int
 	Body           []byte
@@ -99,6 +96,7 @@ type RequestOutput struct {
 	Error          *errorResp
 }
 
+// Request constructs and sends the request
 func (c *DetaClient) Request(i *RequestInput) (*RequestOutput, error) {
 	marshalled := []byte("")
 	if i.Body != nil {

service/base/base.go

@@ -40,12 +40,12 @@ type Query []map[string]interface{}
 // Updates is a datatype to provide updates to an item in an Update operation
 type Updates map[string]interface{}
 
-// NewBase returns a pointer to a new Base
+// New returns a pointer to a new Base
 func New(d *deta.Deta, baseName string) (*Base, error) {
 	if d == nil {
 		return nil, deta.ErrEmptyDetaInstance
 	}
-	if baseName == ""  {
+	if baseName == "" {
 		return nil, deta.ErrBadBaseName
 	}
 	projectKey := d.ProjectKey
@@ -271,15 +271,15 @@ func (b *Base) updatesToUpdateRequest(updates Updates) *updateRequest {
 		Trim:      make([]string, 0),
 	}
 	for k, v := range updates {
-		switch v.(type) {
+		switch val := v.(type) {
 		case *trimUtil:
 			updateReq.Trim = append(updateReq.Trim, k)
 		case *appendUtil:
-			updateReq.Append[k] = v.(*appendUtil).value
+			updateReq.Append[k] = val.value
 		case *prependUtil:
-			updateReq.Prepend[k] = v.(*prependUtil).value
+			updateReq.Prepend[k] = val.value
 		case *incrementUtil:
-			updateReq.Increment[k] = v.(*incrementUtil).value
+			updateReq.Increment[k] = val.value
 		default:
 			updateReq.Set[k] = v
 		}
@@ -341,7 +341,7 @@ type fetchResponse struct {
 
 func (b *Base) fetch(req *fetchRequest) (*fetchResponse, error) {
 	o, err := b.client.Request(&client.RequestInput{
-		Path:   fmt.Sprintf("/query"),
+		Path:   "/query",
 		Method: "POST",
 		Body:   req,
 	})

service/base/doc.go

@@ -0,0 +1,73 @@
+/*
+Package base is the Deta Base service package.
+
+The following is a simple Put operation example.
+
+	import (
+		"fmt"
+		"os"
+
+		"github.com/deta/deta-go/deta"
+		"github.com/deta/deta-go/service/base"
+	)
+
+	// User an example user struct
+	type User struct {
+		Key      string   `json:"key"` // json struct tag 'key' used to denote the key
+		Username string   `json:"username"`
+		Active   bool     `json:"active"`
+		Age      int      `json:"age"`
+		Likes    []string `json:"likes"`
+	}
+
+	func main() {
+		// Create a new Deta instance with a project key
+		d, err := deta.New(deta.WithProjectKey("project_key"))
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "failed to create new Deta instance: %v\n", err)
+			os.Exit(1)
+		}
+
+		// Create a new Base instance called "users", provide the previously created Deta instance
+		users, err := base.New(d, "users")
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "failed to create new Base instance: %v\n", err)
+			os.Exit(1)
+		}
+
+		// Put "jimmy" to the "users" Base
+		key, err := db.Put(&User{
+			Key: "jimmy_neutron",
+			Username: "jimmy",
+			Active: true,
+			Age: 20,
+			Likes: []string{"science"},
+		})
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "failed to put item: %v\n", err)
+			os.Exit(1)
+		}
+		fmt.Printf("successfully put item with key %s\n", key)
+
+		// A map can also be used
+		jimmy := map[string]interface{}{
+			"key":      "jimmy_neutron",
+			"username": "jimmy",
+			"active":   true,
+			"age":      20,
+			"likes":    []string{"science"},
+		}
+		key, err = db.Put(jimmy)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "failed to put item: %v\n", err)
+			os.Exit(1)
+		}
+		fmt.Printf("successfully put item with key: %s\n", key)
+	}
+
+More examples and complete documentation on https://docs.deta.sh/docs/base/sdk
+
+
+
+*/
+package base

service/drive/doc.go

@@ -0,0 +1,54 @@
+/*
+Package drive is the Deta Drive service package.
+
+The following is a simple Put operation example.
+
+	import (
+		"bufio"
+		"fmt"
+		"os"
+
+		"github.com/deta/deta-go/deta"
+		"github.com/deta/deta-go/service/drive"
+	)
+
+	func main() {
+		// Create a new Deta instance with a project key
+		d, err := deta.New(deta.WithProjectKey("project_key"))
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "failed to create new Deta instance:%v\n", \n)
+			os.Exit(1)
+		}
+
+		// Create a new Drive instance called "drawings", provide the previously created Deta instance
+		drawings, err := drive.New(d, "drawings")
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "failed to create new Drive instance: %v\n", err)
+			os.Exit(1)
+		}
+
+		// Open local file "art.svg"
+		file, err := os.Open("./art.svg")
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "failed to open file: %v\n", err)
+			os.Exit(1)
+		}
+		defer file.Close()
+
+		// Put "art.svg" to "drawings"
+		name, err := drawings.Put(&drive.PutInput{
+			Name:        "art.svg",
+			Body:        bufio.NewReader(file),
+			ContentType: "image/svg+xml",
+		})
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "failed to put file: %v\n", err)
+			os.Exit(1)
+		}
+		fmt.Printf("successfully put file %s", name)
+	}
+
+More examples and complete documentation on https://docs.deta.sh/docs/drive/sdk/
+
+*/
+package drive

service/drive/drive.go

@@ -1,3 +1,4 @@
+// Package drive is the Deta Drive service package.
 package drive
 
 import (
@@ -23,7 +24,7 @@ type Drive struct {
 	client *client.DetaClient
 }
 
-// NewDrive returns a pointer to new Drive
+// New returns a pointer to new Drive
 func New(d *deta.Deta, driveName string) (*Drive, error) {
 	if d == nil {
 		return nil, deta.ErrEmptyDetaInstance