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/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)