Add comments to exported functions.

client_hooks.go

@@ -17,32 +17,50 @@ import (
 	"net/http"
 )
 
+// ClientOption is a functional option for extending a Twirp client.
 type ClientOption func(*ClientOptions)
 
+// ClientOptions encapsulate the configurable parameters on a Twirp client.
 type ClientOptions struct {
 	Hooks *ClientHooks
 }
 
+// ClientHooks is a container for callbacks that can instrument a
+// Twirp-generated client. These callbacks all accept a context and some return
+// a context. They can use this to add to the contxt, appending values or
+// deadlilns to it.
+//
+// The RequestPrepared hook is special because it can return errors. If it
+// returns non-nil error, handling for that request will be stopped at that
+// point. The Error hook will then be triggered.
+//
+// The RequestPrepaared hook will always be called first and wlil be called for
+// every outgoinig request from the Twirp client. The last hook to be called
+// will either be Error or ResponseReceived, so be sure to handle both case in
+// your hooks.
 type ClientHooks struct {
 	// RequestPrepared is called as soon as a request has been created and before it has been sent
 	// to the Twirp server.
 	RequestPrepared func(context.Context, *http.Request) (context.Context, error)
 
 	// ResponseReceived is called after a request has finished sending. Since this is terminal, the context is
-	// not returned.
+	// not returned. ResponseReceived will not be called in the case of an error
+	// being returned from the request.
 	ResponseReceived func(context.Context)
 
 	// Error hook is called whenever an error occurs during the sending of a request. The Error is passed
 	// as an argument to the hook.
 	Error func(context.Context, Error)
 }
 
+// DefaultClientOptions instantiates ClientOptions with their default options.
 func DefaultClientOptions() ClientOptions {
 	return ClientOptions{
 		Hooks: nil,
 	}
 }
 
+// WithClientHooks defines the hooks for a Twirp client.
 func WithClientHooks(hooks *ClientHooks) ClientOption {
 	return func(o *ClientOptions) {
 		o.Hooks = hooks