update doc strings; and add package-level docs

atproto/client/admin_auth.go

···
 	"github.com/bluesky-social/indigo/atproto/syntax"
 )
 
+// Simple [AuthMethod] implementation for atproto "admin auth".
 type AdminAuth struct {
 	Password string
 }

atproto/client/apiclient.go

···
 	"github.com/bluesky-social/indigo/atproto/syntax"
 )
 
+// Interface for auth implementations which can be used with [APIClient].
 type AuthMethod interface {
-	// endpoint parameter is included for auth methods which need to include the NSID in authorization tokens
+	// Endpoint parameter is included for auth methods which need to include the NSID in authorization tokens
 	DoWithAuth(c *http.Client, req *http.Request, endpoint syntax.NSID) (*http.Response, error)
 }
 
+// General purpose client for atproto "XRPC" API endpoints.
 type APIClient struct {
-	// inner HTTP client
+	// Inner HTTP client. May be customized after the overall [APIClient] struct is created; for example to set a default request timeout.
 	Client *http.Client
 
-	// host URL prefix: scheme, hostname, and port. This field is required.
+	// Host URL prefix: scheme, hostname, and port. This field is required.
 	Host string
 
-	// optional auth client "middleware"
+	// Optional auth client "middleware".
 	Auth AuthMethod
 
-	// optional HTTP headers which will be included in all requests. Only a single value per key is included; request-level headers will override any client-level defaults.
+	// Optional HTTP headers which will be included in all requests. Only a single value per key is included; request-level headers will override any client-level defaults.
 	Headers http.Header
 
-	// optional authenticated account DID for this client. Does not change client behavior; this is included as a convenience for calling code, logging, etc.
+	// optional authenticated account DID for this client. Does not change client behavior; this field is included as a convenience for calling code, logging, etc.
 	AccountDID *syntax.DID
 }
 
 // Creates a simple APIClient for the provided host. This is appropriate for use with unauthenticated ("public") atproto API endpoints, or to use as a base client to add authentication.
 //
-// Uses the default stdlib http.Client, and sets a default User-Agent.
+// Uses [http.DefaultClient], and sets a default User-Agent.
 func NewAPIClient(host string) *APIClient {
 	return &APIClient{
 		Client: http.DefaultClient,
···
 
 // High-level helper for simple JSON "Query" API calls.
 //
-// Does not work with all API endpoints. For more control, use the Do() method with APIRequest.
+// This method automatically parses non-successful responses to [APIError].
+//
+// For Query endpoints which return non-JSON data, or other situations needing complete configuration of the request and response, use the [APIClient.Do] method.
 func (c *APIClient) Get(ctx context.Context, endpoint syntax.NSID, params map[string]any, out any) error {
 
 	req := NewAPIRequest(http.MethodGet, endpoint, nil)
···
 
 // High-level helper for simple JSON-to-JSON "Procedure" API calls, with no query params.
 //
-// Does not work with all possible atproto API endpoints. For more control, use the Do() method with APIRequest.
+// This method automatically parses non-successful responses to [APIError].
+//
+// For Query endpoints which expect non-JSON request bodies; return non-JSON responses; direct use of [io.Reader] for the request body; or other situations needing complete configuration of the request and response, use the [APIClient.Do] method.
 func (c *APIClient) Post(ctx context.Context, endpoint syntax.NSID, body any, out any) error {
 	bodyJSON, err := json.Marshal(body)
 	if err != nil {
···
 
 // Full-featured method for atproto API requests.
 //
-// NOTE: this does not currently parse error response JSON body, thought it might in the future.
+// TODO: this does not currently parse API error response JSON body to [APIError], thought it might in the future.
 func (c *APIClient) Do(ctx context.Context, req *APIRequest) (*http.Response, error) {
 
 	if c.Client == nil {
···
 
 // Returns a shallow copy of the APIClient with the provided service ref configured as a proxy header.
 //
-// To configure service proxying without creating a copy, simply set the "Atproto-Proxy" header.
+// To configure service proxying without creating a copy, simply set the 'Atproto-Proxy' header.
 func (c *APIClient) WithService(ref string) *APIClient {
 	hdr := c.Headers.Clone()
 	hdr.Set("Atproto-Proxy", ref)
···
 	return &out
 }
 
-// Configures labeler header (Atproto-Accept-Labelers) with the indicated "redact" level labelers, and regular labelers.
+// Configures labeler header ('Atproto-Accept-Labelers') with the indicated "redact" level labelers, and regular labelers.
+//
+// Overwrites any existing client-level header value.
 func (c *APIClient) SetLabelers(redact, other []syntax.DID) {
 	c.Headers.Set("Atproto-Accept-Labelers", encodeLabelerHeader(redact, other))
 }

atproto/client/apirequest.go

···
 )
 
 var (
-	// atproto API "Query" Lexicon method, which is HTTP GET. Not to be confused with proposed "HTTP QUERY" method.
+	// atproto API "Query" Lexicon method, which is HTTP GET. Not to be confused with the IETF draft "HTTP QUERY" method.
 	MethodQuery = http.MethodGet
 
 	// atproto API "Procedure" Lexicon method, which is HTTP POST.
···
 	// Optional request body (may be nil). If this is provided, then 'Content-Type' header should be specified
 	Body io.Reader
 
-	// Optional function to return new reader for request body; used for retries. strongly recommended if Body is defined. Body still needs to be defined, even if this function is provided.
+	// Optional function to return new reader for request body; used for retries. Strongly recommended if Body is defined. Body still needs to be defined, even if this function is provided.
 	GetBody func() (io.ReadCloser, error)
 
 	// Optional query parameters (field may be nil). These will be encoded as provided.
···
 
 // Initializes a new request struct. Initializes Headers and QueryParams so they can be manipulated immediately.
 //
-// If body is provided (it can be nil), will try to turn it in to the most retry-able form (and wrap as io.ReadCloser).
+// If body is provided (it can be nil), will try to turn it in to the most retry-able form (and wrap as [io.ReadCloser]).
 func NewAPIRequest(method string, endpoint syntax.NSID, body io.Reader) *APIRequest {
 	req := APIRequest{
 		Method:      method,
···
 	return &req
 }
 
-// Creates an `http.Request` for this API request.
+// Creates an [http.Request] for this API request.
 //
 // `host` parameter should be a URL prefix: schema, hostname, port (required)
-// `headers` parameters are treated as client-level defaults. Only a single value is allowed per key ("Set" behavior), and will be clobbered by any request-level header values. (optional; may be nil)
+//
+// `clientHeaders`, if provided, is treated as client-level defaults. Only a single value is allowed per key ("Set" behavior), and will be clobbered by any request-level header values. (optional; may be nil)
 func (r *APIRequest) HTTPRequest(ctx context.Context, host string, clientHeaders http.Header) (*http.Request, error) {
 	u, err := url.Parse(host)
 	if err != nil {

atproto/client/doc.go

···
+/*
+General-purpose client for atproto "XRPC" HTTP API endpoints.
+
+[APIClient] wraps an [http.Client] and provides an ergonomic atproto-specific (but not Lexicon-specific) interface for "Query" (GET) and "Procedure" (POST) endpoints. It does not support "Event Stream" (WebSocket) endpoints. The client is expected to be used with a single host at a time, though it does have special support ([APIClient.WithService]) for proxied service requests when connected to a PDS host. The client does not authenticate requests by default, but supports pluggable authentication methods (see below). The [APIReponse] struct represents a generic API request, and helps with conversion to an [http.Request].
+
+The [APIError] struct can represent a generic API error response (eg, an HTTP response with a 4xx or 5xx response code), including the 'error' and 'message' JSON response fields expected with atproto. It is intended to be used with [errors.Is] in error handling, or to provide helpful error messages.
+
+The [AuthMethod] interface allows [APIClient] to work with multiple forms of authentication in atproto. It is expected that more complex auth systems (eg, those using signed JWTs) will be implemented in separate packages, but this package does include two simple auth methods:
+
+- [PasswordAuth] is the original PDS user auth method, using access and refresh tokens.
+- [AdminAuth] is simple HTTP Basic authentication for administrative requests, as implemented by many atproto services (Relay, Ozone, PDS, etc).
+
+## Design Notes
+
+Several [AuthMethod] implementations are expected to require retrying entire request at unexpected times. For example, unexpected OAuth DPoP nonce changes, or unexpected password session token refreshes. The auth method may also need to make requests to other servers as part of the refresh process (eg, OAuth when working with a PDS/entryway split). This means that requests should be "retryable" as often as possible. This is mostly a concern for Procedures (HTTP POST) with a non-empty body. The [http.Client] will attempt to "unclose" some common [io.ReadCloser] types (like [bytes.Buffer]), but others may need special handling, using the [APIRequest.GetBody] method. This package will try to make types implementing [io.Seeker] tryable; this helps with things like passing in a open file descriptor for file uploads.
+
+In theory, the [http.RoundTripper] interface could have been used instead of [AuthMethod]; or auth methods could have been injected in to [http.Client] instances directly. This package avoids this pattern for a few reasons. The first is that wrangling layered stacks of [http.RoundTripper] can become cumbersome. Calling code may want to use [http.Client] variants which add observability, retries, circuit-breaking, or other non-auth customization. Secondly, some atproto auth methods will require requests to other servers or endpoints, and having a common [http.Client] to re-use for these requests makes sense. Finally, several atproto auth methods need to know the target endpoint as an NSID; while this could be re-parsed from the request URL, it is simpler and more reliable to pass it as an argument.
+
+This package tries to use minimal dependencies beyond the Go standard library, to make it easy to reference as a dependency. It does require the [github.com/bluesky-social/indigo/atproto/syntax] and [github.com/bluesky-social/indigo/atproto/identity] sibling packages. In particular, this package does not include any auth methods requiring JWTs, to avoid adding any specific JWT implementation as a dependency.
+*/
+package client

atproto/client/lexclient.go

···
 	"github.com/bluesky-social/indigo/atproto/syntax"
 )
 
-// Implements the `LexClient` interface, for use with code-generated API helpers.
+// Implements the [github.com/bluesky-social/indigo/lex/util.LexClient] interface, for use with code-generated API helpers.
 func (c *APIClient) LexDo(ctx context.Context, kind string, inpenc string, method string, params map[string]any, bodyobj any, out any) error {
 	// some of the code here is copied from indigo:xrpc/xrpc.go
 

atproto/client/password_auth.go

···
 
 type RefreshCallback = func(ctx context.Context, data PasswordSessionData)
 
+// Implementation of [AuthMethod] for password-based auth sessions with atproto PDS hosts. Automatically refreshes "access token" using a "refresh token" when needed.
+//
+// It is safe to use this auth method concurrently from multiple goroutines.
 type PasswordAuth struct {
 	Session PasswordSessionData
 
···
 	lk sync.RWMutex
 }
 
+// Data about a PDS password auth session which can be persisted and then used to resume the session later.
 type PasswordSessionData struct {
 	AccessToken  string     `json:"access_token"`
 	RefreshToken string     `json:"refresh_token"`
···
 	Host         string     `json:"host"`
 }
 
+// Creates a deep copy of the session data.
 func (sd *PasswordSessionData) Clone() PasswordSessionData {
 	return PasswordSessionData{
 		AccessToken:  sd.AccessToken,
···
 	if err != nil {
 		return nil, err
 	}
-	// TODO: could handle auth failure as special error type here
+	// NOTE: could handle auth failure as special error type here
 	return retryResp, err
 }
 
···
 // Refreshes auth tokens (takes a write-lock on session data).
 //
 // `priorRefreshToken` argument is used to check if a concurrent refresh already took place.
-//
-// TODO: need a "Logout" method as well? which takes the refresh token (not access token)
 func (a *PasswordAuth) Refresh(ctx context.Context, c *http.Client, priorRefreshToken string) error {
 
 	a.lk.Lock()
···
 		if err := json.NewDecoder(resp.Body).Decode(&eb); err != nil {
 			return &APIError{StatusCode: resp.StatusCode}
 		}
-		// TODO: indicate in this error that it was from refresh process, not original request?
+		// TODO: indicate in the error that it was from refresh process, not original request?
 		return eb.APIError(resp.StatusCode)
 	}
 
···
 	return nil
 }
 
-// Creates a new APIClient with PasswordAuth for the provided user. The provided identity directory is used to resolve the PDS host for the account.
+// Creates a new [APIClient] with [PasswordAuth] for the provided user. The provided identity directory is used to resolve the PDS host for the account.
 //
 // `authToken` is optional; is used when multi-factor authentication is enabled for the account.
-// `cb` is an optional callback which will be called with updated session data after any token refresh, in a goroutine.
+//
+// `cb` is an optional callback which will be called with updated session data after any token refresh.
 func LoginWithPassword(ctx context.Context, dir identity.Directory, username syntax.AtIdentifier, password, authToken string, cb RefreshCallback) (*APIClient, error) {
 
 	ident, err := dir.Lookup(ctx, username)
···
 	return c, nil
 }
 
-// Creates a new APIClient with PasswordAuth, based on a login to the provided host. Note that with some PDS implementations, 'username' could be an email address. This login method also works in situations where an account's network identity does not resolve to this specific host.
+// Creates a new [APIClient] with [PasswordAuth], based on a login to the provided host. Note that with some PDS implementations, 'username' could be an email address. This login method also works in situations where an account's network identity does not resolve to this specific host.
 //
 // `authToken` is optional; is used when multi-factor authentication is enabled for the account.
-// `cb` is an optional callback which will be called with updated session data after any token refresh, in a goroutine.
+//
+// `cb` is an optional callback which will be called with updated session data after any token refresh.
 func LoginWithPasswordHost(ctx context.Context, host, username, password, authToken string, cb RefreshCallback) (*APIClient, error) {
 
 	c := NewAPIClient(host)
···
 	return c, nil
 }
 
-// Creates an APIClient using PasswordAuth, based on existing session data.
+// Creates an [APIClient] using [PasswordAuth], based on existing session data.
 //
-// `cb` is an optional callback which will be called with updated session data after any token refresh, in a goroutine.
+// `cb` is an optional callback which will be called with updated session data after any token refresh.
 func ResumePasswordSession(data PasswordSessionData, cb RefreshCallback) *APIClient {
 	c := NewAPIClient(data.Host)
 	ra := PasswordAuth{