improved Go doc

README.md

@@ -2,6 +2,10 @@
 
 Go package for the Who's On First "standard places responses" (SPR) interface.
 
+## Documentation
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/whosonfirst/go-whosonfirst-spr.svg)](https://pkg.go.dev/github.com/whosonfirst/go-whosonfirst-spr)
+
 ## Description
 
 The `StandardPlacesResult` (SPR) interface defines the _minimum_ set of methods that a system working with a collection of Who's On First (WOF) must implement for any given record. Not all records are the same so the SPR interface is meant to serve as a baseline for common data that describes every record.
@@ -12,44 +16,6 @@ Being a [Go language interface type](https://www.alexedwards.net/blog/interfaces
 
 For a concrete example of a package that implements the `SPR` have a look at the [go-whosonfirst-sqlite-spr](https://github.com/whosonfirst/go-whosonfirst-sqlite-spr) package.
 
-## Usage
-
-```
-import "github.com/whosonfirst/go-whosonfirst-spr/v2"
-```
-
-## Interface
-
-```
-type StandardPlacesResult interface {
-	Id() string
-	ParentId() string
-	Name() string
-	Placetype() string
-	Country() string
-	Repo() string
-	Path() string
-	URI() string
-	Inception() *edtf.EDTFDate
-	Cessation() *edtf.EDTFDate	
-	Latitude() float64
-	Longitude() float64
-	MinLatitude() float64
-	MinLongitude() float64
-	MaxLatitude() float64
-	MaxLongitude() float64
-	IsCurrent() flags.ExistentialFlag
-	IsCeased() flags.ExistentialFlag
-	IsDeprecated() flags.ExistentialFlag
-	IsSuperseded() flags.ExistentialFlag
-	IsSuperseding() flags.ExistentialFlag
-	SupersededBy() []int64
-	Supersedes() []int64
-	BelongsTo() []int64
-	LastModified() int64
-}
-```
-
 ### Notes
 
 * The `Id()` and `ParentId()` methods return `string` (rather than `int64`) values to account for non-WOF GeoJSON documents that are consumed by the `whosonfirst/go-whosonfirst-geojson-v2` package.

doc.go

@@ -0,0 +1,11 @@
+// package spr provides an interface which defines the minimum set of methods that a system working with a collection of Who's On First (WOF) must implement for any given record. Not all records are the same so the SPR interface is meant to serve as a baseline for common data that describes every record.
+//
+// The `StandardPlacesResult` (SPR) interface defines the _minimum_ set of methods that a system working with a collection of Who's On First (WOF) must implement for any given record. Not all records are the same so the SPR interface is meant to serve as a baseline for common data that describes every record.
+//
+// The `StandardPlacesResults` takes the Flickr [standard photo response](https://code.flickr.net/2008/08/19/standard-photos-response-apis-for-civilized-age) as its inspiration which was designed to be the minimum amount of information about a Flickr photo necessary to display that photo with proper attribution and a link back to the photo page itself. The `StandardPlacesResults` aims to achieve the same thing for WOF records.
+//
+// Being a [Go language interface type](https://www.alexedwards.net/blog/interfaces-explained) the SPR is _not_ designed as a data exchange method. Any given implementation of the SPR _may_ allow its internal data to be exported or serialized (for example, as JSON) but this is not a requirement.
+//
+// For a concrete example of a package that implements the `SPR` have a look at the [go-whosonfirst-sqlite-spr](https://github.com/whosonfirst/go-whosonfirst-sqlite-spr) package.
+package spr
+

spr.go

@@ -5,43 +5,62 @@ import (
 	"github.com/whosonfirst/go-whosonfirst-flags"
 )
 
+// StandardPlacesResult is an interface which defines the minimum set of methods that a system working with a collection of Who's On First (WOF) must implement for any given record. Not all records are the same so the SPR interface is meant to serve as a baseline for common data that describes every record.
 type StandardPlacesResult interface {
+	// The unique ID of the place result
 	Id() string
+	// The unique parent ID of the place result
 	ParentId() string
+	// The name of the place result
 	Name() string
+	// The Who's On First placetype of the place result	
 	Placetype() string
+	// The two-letter country code of the place result
 	Country() string
+	// The (Git) repository name where the source record for the place result is stored.
 	Repo() string
+	// The relative path for the Who's On First record associated with the place result
 	Path() string
+	// The fully-qualified URI (URL) for the Who's On First record associated with the place result	
 	URI() string
+	// The EDTF inception date of the place result
 	Inception() *edtf.EDTFDate
+	// The EDTF cessation date of the place result	
 	Cessation() *edtf.EDTFDate
+	// The latitude for the principal centroid (typically "label") of the place result
 	Latitude() float64
+	// The longitude for the principal centroid (typically "label") of the place result	
 	Longitude() float64
+	// The minimum latitude of the bounding box of the place result
 	MinLatitude() float64
+	// The minimum longitude of the bounding box of the place result	
 	MinLongitude() float64
+	// The maximum latitude of the bounding box of the place result	
 	MaxLatitude() float64
+	// The maximum longitude of the bounding box of the place result	
 	MaxLongitude() float64
+	// The Who's On First "existential" flag denoting whether the place result is "current" or not
 	IsCurrent() flags.ExistentialFlag
+	// The Who's On First "existential" flag denoting whether the place result is "ceased" or not	
 	IsCeased() flags.ExistentialFlag
+	// The Who's On First "existential" flag denoting whether the place result is superseded or not		
 	IsDeprecated() flags.ExistentialFlag
+	// The Who's On First "existential" flag denoting whether the place result has been superseded	
 	IsSuperseded() flags.ExistentialFlag
+	// The Who's On First "existential" flag denoting whether the place result supersedes other records		
 	IsSuperseding() flags.ExistentialFlag
+	// The list of Who's On First IDs that supersede the place result
 	SupersededBy() []int64
+	// The list of Who's On First IDs that are superseded by the place result	
 	Supersedes() []int64
+	// The list of Who's On First IDs that are ancestors of the place result	
 	BelongsTo() []int64
+	// The Unix timestamp indicating when the place result was last modified
 	LastModified() int64
 }
 
-type Pagination interface {
-	Pages() int
-	Page() int
-	PerPage() int
-	Total() int
-	Cursor() string
-	NextQuery() string
-}
-
+// StandardPlacesResults provides an interface for returning a list of `StandardPlacesResult` results
 type StandardPlacesResults interface {
+	// Results is a list of `StandardPlacesResult` instances.
 	Results() []StandardPlacesResult
 }

util/map.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 )
 
+// SPRToMap converts 's' to a `map[string]string` instance.
 func SPRToMap(s spr.StandardPlacesResult) (map[string]string, error) {
 
 	attrs := make(map[string]string)

util/util.go

@@ -0,0 +1,2 @@
+// package util provides helper (utility) methods for working with SPR instances.
+package util