doc: cleanup and improve for recently moved pkgs (#354)

* chore(atomicx): review docs and add usage example

* chore(fsx): improve docs, return value, add examples

* fix(kvstore): correct typo and add example

* fix(multierror): add basic example

* doc: revamp ooapi documentation

internal/ooapi/client.go

@@ -3,11 +3,16 @@ package ooapi
 // Client is a client for speaking with the OONI API. Make sure you
 // fill in the mandatory fields.
 type Client struct {
-	BaseURL      string       // optional
-	GobCodec     GobCodec     // optional
-	HTTPClient   HTTPClient   // optional
-	JSONCodec    JSONCodec    // optional
-	KVStore      KVStore      // mandatory
-	RequestMaker RequestMaker // optional
-	UserAgent    string       // optional
+	// KVStore is the MANDATORY key-value store. You can use
+	// the kvstore.Memory{} struct for an in-memory store.
+	KVStore KVStore
+
+	// The following fields are optional. When they are empty
+	// we will fallback to sensible defaults.
+	BaseURL      string
+	GobCodec     GobCodec
+	HTTPClient   HTTPClient
+	JSONCodec    JSONCodec
+	RequestMaker RequestMaker
+	UserAgent    string
 }

internal/ooapi/dependencies.go

@@ -6,7 +6,9 @@ import (
 	"net/http"
 )
 
-// JSONCodec is a JSON encoder and decoder.
+// JSONCodec is a JSON encoder and decoder. Generally, we use a
+// default JSONCodec in Client. This is the interface to implement
+// if you want to override such a default.
 type JSONCodec interface {
 	// Encode encodes v as a serialized JSON byte slice.
 	Encode(v interface{}) ([]byte, error)
@@ -15,7 +17,9 @@ type JSONCodec interface {
 	Decode(b []byte, v interface{}) error
 }
 
-// RequestMaker makes an HTTP request.
+// RequestMaker makes an HTTP request. Generally, we use a
+// default RequestMaker in Client. This is the interface to implement
+// if you want to override such a default.
 type RequestMaker interface {
 	// NewRequest creates a new HTTP request.
 	NewRequest(ctx context.Context, method, URL string, body io.Reader) (*http.Request, error)
@@ -29,13 +33,19 @@ type templateExecutor interface {
 	Execute(tmpl string, v interface{}) (string, error)
 }
 
-// HTTPClient is the interface of a generic HTTP client.
+// HTTPClient is the interface of a generic HTTP client. The
+// stdlib's http.Client implements this interface. We use
+// http.DefaultClient as the default HTTPClient used by Client.
+// Consumers of this package typically provide a custom HTTPClient
+// with additional functionality (e.g., DoH, circumvention).
 type HTTPClient interface {
 	// Do should work like http.Client.Do.
 	Do(req *http.Request) (*http.Response, error)
 }
 
-// GobCodec is a Gob encoder and decoder.
+// GobCodec is a Gob encoder and decoder. Generally, we use a
+// default GobCodec in Client. This is the interface to implement
+// if you want to override such a default.
 type GobCodec interface {
 	// Encode encodes v as a serialized gob byte slice.
 	Encode(v interface{}) ([]byte, error)
@@ -44,7 +54,9 @@ type GobCodec interface {
 	Decode(b []byte, v interface{}) error
 }
 
-// KVStore is a key-value store.
+// KVStore is a key-value store. This is the interface the
+// client expect for the key-value store used to save persistent
+// state (typically on the file system).
 type KVStore interface {
 	// Get gets a value from the key-value store.
 	Get(key string) ([]byte, error)

internal/ooapi/doc.go

@@ -15,9 +15,6 @@
 // perform the login. If an API uses caching, we will
 // automatically use the cache.
 //
-// See the example describing auto-login for more information
-// on how to use auto-login.
-//
 // Design
 //
 // Most of the code in this package is auto-generated from the
@@ -46,11 +43,11 @@
 //
 // Architecture
 //
-// The ./apimodel package contains the definition of request
+// The ./apimodel sub-package contains the definition of request
 // and response messages. We rely on tagging to specify how
 // we should encode and decode messages.
 //
-// The ./internal/generator contains code to generate most
+// The ./internal/generator sub-package contains code to generate most
 // code in this package. In particular, the spec.go file is
 // the specification of the APIs.
 package ooapi

internal/ooapi/example_test.go

@@ -0,0 +1,36 @@
+package ooapi_test
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/ooni/probe-cli/v3/internal/kvstore"
+	"github.com/ooni/probe-cli/v3/internal/ooapi"
+	"github.com/ooni/probe-cli/v3/internal/ooapi/apimodel"
+)
+
+func ExampleClient() {
+	clnt := &ooapi.Client{
+		KVStore: &kvstore.Memory{},
+	}
+	ctx := context.Background()
+	resp, err := clnt.CheckIn(ctx, &apimodel.CheckInRequest{
+		Charging:        false,
+		OnWiFi:          false,
+		Platform:        "linux",
+		ProbeASN:        "AS30722",
+		ProbeCC:         "IT",
+		RunType:         "timed",
+		SoftwareName:    "miniooni",
+		SoftwareVersion: "0.1.0-dev",
+		WebConnectivity: apimodel.CheckInRequestWebConnectivity{
+			CategoryCodes: []string{"NEWS"},
+		},
+	})
+	fmt.Printf("%+v\n", err)
+	// Output: <nil>
+	if resp == nil {
+		log.Fatal("expected non-nil response")
+	}
+}