Merge pull request #1219 from cpuguy83/fixup_docstrings

Add more details to a few doc strings

client/client.go

@@ -1,3 +1,88 @@
+/*
+Package client implements everything required for interacting with a Notary repository.
+
+Usage
+
+Use this package by creating a new repository object and calling methods on it.
+
+	package main
+
+	import (
+		"encoding/hex"
+		"fmt"
+		"net/http"
+		"os"
+		"time"
+
+		"github.com/docker/distribution/registry/client/auth"
+		"github.com/docker/distribution/registry/client/auth/challenge"
+		"github.com/docker/distribution/registry/client/transport"
+		notary "github.com/docker/notary/client"
+		"github.com/docker/notary/trustpinning"
+		"github.com/docker/notary/tuf/data"
+	)
+
+	func main() {
+		rootDir := ".trust"
+		if err := os.MkdirAll(rootDir, 0700); err != nil {
+			panic(err)
+		}
+
+		server := "https://notary.docker.io"
+		image := "docker.io/library/alpine"
+		repo, err := notary.NewFileCachedNotaryRepository(
+			rootDir,
+			data.GUN(image),
+			server,
+			makeHubTransport(server, image),
+			nil,
+			trustpinning.TrustPinConfig{},
+		)
+
+		targets, err := repo.ListTargets()
+		if err != nil {
+			panic(err)
+		}
+
+		for _, tgt := range targets {
+			fmt.Printf("%s\t%s\n", tgt.Name, hex.EncodeToString(tgt.Hashes["sha256"]))
+		}
+	}
+
+	func makeHubTransport(server, image string) http.RoundTripper {
+		base := http.DefaultTransport
+		modifiers := []transport.RequestModifier{
+			transport.NewHeaderRequestModifier(http.Header{
+				"User-Agent": []string{"my-client"},
+			}),
+		}
+
+		authTransport := transport.NewTransport(base, modifiers...)
+		pingClient := &http.Client{
+			Transport: authTransport,
+			Timeout:   5 * time.Second,
+		}
+		req, err := http.NewRequest("GET", server+"/v2/", nil)
+		if err != nil {
+			panic(err)
+		}
+
+		challengeManager := challenge.NewSimpleManager()
+		resp, err := pingClient.Do(req)
+		if err != nil {
+			panic(err)
+		}
+		defer resp.Body.Close()
+		if err := challengeManager.AddResponse(resp); err != nil {
+			panic(err)
+		}
+		tokenHandler := auth.NewTokenHandler(base, nil, image, "pull")
+		modifiers = append(modifiers, auth.NewAuthorizer(challengeManager, tokenHandler, auth.NewBasicHandler(nil)))
+
+		return transport.NewTransport(base, modifiers...)
+	}
+
+*/
 package client
 
 import (

trustpinning/trustpin.go

@@ -12,9 +12,24 @@ import (
 
 // TrustPinConfig represents the configuration under the trust_pinning section of the config file
 // This struct represents the preferred way to bootstrap trust for this repository
+// This is fully optional. If left at the default, uninitialized value Notary will use TOFU over
+// HTTPS.
+// You can use this to provide certificates or a CA to pin to as a root of trust for a GUN.
+// These are used with the following precedence:
+//
+// 1. Certs
+// 2. CA
+// 3. TOFUS (TOFU over HTTPS)
+//
+// Only one trust pinning option will be used to validate a particular GUN.
 type TrustPinConfig struct {
-	CA          map[string]string
-	Certs       map[string][]string
+	// CA maps a GUN prefix to file paths containing the root CA.
+	// This file can contain multiple root certificates, bundled in separate PEM blocks.
+	CA map[string]string
+	// Certs maps a GUN to a list of certificate IDs
+	Certs map[string][]string
+	// DisableTOFU, when true, disables "Trust On First Use" of new key data
+	// This is false by default, which means new key data will always be trusted the first time it is seen.
 	DisableTOFU bool
 }
 

tuf/data/types.go

@@ -19,7 +19,9 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
-// GUN type for specifying gun
+// GUN is a Globally Unique Name. It is used to identify trust collections.
+// An example usage of this is for container image repositories.
+// For example: myregistry.io/myuser/myimage
 type GUN string
 
 func (g GUN) String() string {