update docs, vendor deps

README.md

@@ -91,11 +91,17 @@ $> ll /usr/local/data/whosonfirst-data-admin-xy.pb
 
 ## Concepts
 
+### Iterators
+
+An iterator is a valid `whosonfirst/go-whosonfirst-iterate/v2` instance (or URI used to create that instance) that is the source of records to pass to a (findingaid) producer.
+
 ### Producers
 
+Producers implement the `producer.Producer` interface and are used to populate finding aids where "populate" means updating a data store with information mapping a Who's On First ID to its corresponding repository name.
+
 ### Providers
 
-### Iterators
+Providers implement the `provider.Provider` interface and are used to generate a list of iterator URIs for crawling by a producer.
 
 ## Tools
 

cmd/populate/main.go

@@ -22,7 +22,7 @@ func main() {
 
 	iterator_uri := flag.String("iterator-uri", "repo://", "A valid whosonfirst/go-whosonfirst-iterate/v2 URI.")
 
-	provider_uri := flag.String("provider-uri", "", "A valid whosonfirst/go-whosonfirst-findingaid/v2/provider URI to use for deriving additional sources.")
+	provider_uri := flag.String("provider-uri", "", "An optional whosonfirst/go-whosonfirst-findingaid/v2/provider URI to use for deriving additional sources.")
 
 	producer_uri := flag.String("producer-uri", "csv://?archive=archive.tar.gz", "A valid whosonfirst/go-whosonfirst-findingaid/v2/producer URI.")
 

producer/producer.go

@@ -1,3 +1,4 @@
+// package producer provides interfaces used to populate a finding aid where "populate" means updating a data store with information mapping a Who's On First ID to its corresponding repository name.
 package producer
 
 import (
@@ -7,7 +8,9 @@ import (
 	"net/url"
 )
 
+// Producer provides an interfaces used to populate a finding aid where "populate" means updating a data store with information mapping a Who's On First ID to its corresponding repository name.
 type Producer interface {
+	// PopulateWithIterator will crawl one or more paths with a `whosonfirst/go-whosonfirst-iterate/v2` iterator instance and populate a finding aid with each record encountered.
 	PopulateWithIterator(context.Context, timings.Monitor, string, ...string) error
 	Close(context.Context) error
 }

provider/provider.go

@@ -1,3 +1,4 @@
+// package provider interfaces used to generate a list of iterator `whosonfirst/go-whosonfirst-iterate/v2` URIs for crawling by a `producer.Producer` instance.
 package provider
 
 import (