Merge pull request #21 from planetlabs/doc-updates

Doc updates

Author: tschaub

crawler/crawler.go

@@ -16,6 +16,10 @@ import (
 	"github.com/tschaub/workgroup"
 )
 
+// RecursionType informs the crawler how to treat linked resources.
+// None will only call the visitor for the first resource.  Children
+// will call the visitor for all child catalogs, collections, and items.
+// All will call the visitor for parent resources as well as child resources.
 type RecursionType string
 
 const (
@@ -113,6 +117,10 @@ func resolveURL(baseUrl string, resourceUrl string) (string, error) {
 	return resolved.String(), nil
 }
 
+// Visitor is called for each resource during crawling.
+//
+// The resource location (URL or file path) is passed as the first argument.
+// Any returned error will stop crawling and be returned by Crawl.
 type Visitor func(string, Resource) error
 
 // Crawler crawls STAC resources.
@@ -168,7 +176,9 @@ func New(visitor Visitor, options ...*Options) *Crawler {
 
 // Crawl calls the visitor for each resolved resource.
 //
-// The resource can be a file path or a URL.
+// The resource can be a file path or a URL.  Any error returned by visitor
+// will stop crawling and be returned by this function.  Context cancellation
+// will also stop crawling and the context error will be returned.
 func (c *Crawler) Crawl(ctx context.Context, resource string) error {
 	resourceUrl, isFilepath, err := normalizeUrl(resource)
 	if err != nil {

crawler/resource.go

@@ -5,12 +5,13 @@ const (
 	extensionsKey = "stac_extensions"
 )
 
+// ResourceType indicates the document-level STAC resource type.
 type ResourceType string
 
 const (
-	Item       = ResourceType("item")
-	Catalog    = ResourceType("catalog")
-	Collection = ResourceType("collection")
+	Item       ResourceType = "item"
+	Catalog    ResourceType = "catalog"
+	Collection ResourceType = "collection"
 )
 
 // Resource represents a STAC catalog, collection, or item.

validator/errors.go

@@ -18,6 +18,9 @@ type ValidationError struct {
 	Resource crawler.Resource
 }
 
+// GoString provides additional detail about the validation error.
+//
+// Called when the # flag is used with the %v verb as in fmt.Printf("%#v", err).
 func (err *ValidationError) GoString() string {
 	return fmt.Sprintf("invalid %s: %s\n%s", err.Resource.Type(), err.Location, err.ValidationError.GoString())
 }

validator/validator.go

@@ -151,7 +151,10 @@ func schemaUrl(version string, resourceType crawler.ResourceType) string {
 
 // Validate validates a STAC resource.
 //
-// The resource can be a path to a local file or a URL.
+// The resource can be a path to a local file or a URL.  Validation will stop
+// with the first invalid resource and the resulting ValidationError will be
+// returned.  Context cancellation will also stop validation and the context
+// error will be returned.
 func (v *Validator) Validate(ctx context.Context, resource string) error {
 	c := crawler.New(v.validate, &crawler.Options{
 		Concurrency: v.concurrency,

validator/validator_test.go

@@ -90,8 +90,7 @@ func TestSuite(t *testing.T) {
 
 func ExampleValidator_Validate_children() {
 	v := validator.New(&validator.Options{
-		Concurrency: 1,
-		Recursion:   crawler.Children,
+		Recursion: crawler.Children,
 	})
 
 	err := v.Validate(context.Background(), "testdata/cases/v1.0.0/catalog-with-item-missing-id.json")
@@ -107,8 +106,7 @@ func ExampleValidator_Validate_children() {
 
 func ExampleValidator_Validate_single() {
 	v := validator.New(&validator.Options{
-		Concurrency: 1,
-		Recursion:   crawler.None,
+		Recursion: crawler.None,
 	})
 
 	err := v.Validate(context.Background(), "testdata/cases/v1.0.0/item-missing-id.json")