Improve documentation - MEDIGO#45

- Add inline doc about credentials so they appear in godoc
- Replace the doc file by a Example file that should run on godocs (https://blog.golang.org/examples)

README.md

@@ -33,6 +33,9 @@ func main() {
 }
 ```
 
+Find the complete API on https://godoc.org/github.com/MEDIGO/go-zendesk/zendesk#NewClient
+
+
 ## Development
 
 ### Linting
@@ -49,7 +52,7 @@ The project contains integration tests that uses the Zendesk API. To execute the
 
 ```
 ZENDESK_DOMAIN=<your-zendesk-domain>
-ZENDESK_USERNAME=<your-zendesk-api-username>
+ZENDESK_USERNAME=<your-zendesk-api-email>
 ZENDESK_PASSWORD=<your-zendesk-api-password>
 ```
 

zendesk/zendesk.go

@@ -1,3 +1,5 @@
+// Package zendesk provides a client for using the Zendesk Core API.
+
 package zendesk
 
 import (
@@ -63,6 +65,9 @@ type client struct {
 }
 
 // NewEnvClient creates a new Client configured via environment variables.
+//
+// Three environment variables are required: ZENDESK_DOMAIN, ZENDESK_USERNAME and ZENDESK_PASSWORD
+// they will provide parameters to the NewClient function
 func NewEnvClient(middleware ...MiddlewareFunction) (Client, error) {
 	domain := os.Getenv("ZENDESK_DOMAIN")
 	if domain == "" {
@@ -83,6 +88,9 @@ func NewEnvClient(middleware ...MiddlewareFunction) (Client, error) {
 }
 
 // NewClient creates a new Client.
+//
+// You can use either a user email/password combination or an API token.
+// For the latter, append /token to the email and use the API token as a password
 func NewClient(domain, username, password string, middleware ...MiddlewareFunction) (Client, error) {
 	baseURL, err := url.Parse(fmt.Sprintf("https://%s.zendesk.com", domain))
 	if err != nil {

zendesk/zendesk_test.go

@@ -0,0 +1,19 @@
+package zendesk_test
+
+import (
+  "log"
+
+  "github.com/MEDIGO/go-zendesk/zendesk"
+)
+
+func Example() {
+    client, err := zendesk.NewClient("domain", "username", "password")
+    if err != nil {
+        log.Fatal(err)
+    }
+    ticket, err := client.ShowTicket(1)
+    if err != nil {
+        log.Fatal(err)
+    }
+    log.Printf("Requester ID is: %d", *ticket.RequesterID)
+}