write go doc comments for most public definitions (#4)

api/api.go

@@ -4,11 +4,15 @@ import (
 	"github.com/deploifai/sdk-go/api/generated"
 )
 
+// API is a type alias for GenericAPI[generated.GQLClient].
+// The generated.GQLClient is generated based on graphQL query schema in this module.
 type API = GenericAPI[generated.GQLClient]
 
+// NewAPI calls NewGenericAPI[generated.GQLClient] function with generated.NewClient as the first argument.
 func NewAPI(gqlEndpoint string, restEndpoint string, headers RequestHeaders) API {
 
 	return NewGenericAPI[generated.GQLClient](generated.NewClient, gqlEndpoint, restEndpoint, headers)
 }
 
+// Provider is a type alias for GenericProvider[generated.GQLClient].
 type Provider GenericProvider[generated.GQLClient]

api/generic_api.go

@@ -11,32 +11,34 @@ import (
 	"net/http"
 )
 
-// GenericAPI is a generic API client that can be used to create a generated GQLClient and a default http RestClient
+// GenericAPI is a generic api client that uses a generated GQLClient and a default http RestClient.
 type GenericAPI[T GQLClient] struct {
 	GQLClient T
 
 	RestClient RestClient
 }
 
-// RequestHeader defines a request header for a http request
+// RequestHeader defines a request header for a http request.
 type RequestHeader struct {
 	Key   string
 	Value string
 }
 
-// RequestHeaders defines a list of RequestHeader
+// RequestHeaders defines a list of RequestHeader(s).
 type RequestHeaders = []RequestHeader
 
-// GQLClient defines the interface for the generated graphQL client
+// GQLClient defines the interface for the generated graphQL client.
 type GQLClient interface{}
 
-// NewGQLClientFunc defines the generated function signature for creating a new GQLClient
+// NewGQLClientFunc defines the signature of the generated function that creates a new GQLClient.
+// The function is generated from the [gqlgenc] tool.
+// [gqlgenc]: https://github.com/Yamashou/gqlgenc
 type NewGQLClientFunc[T GQLClient] func(cli *http.Client, baseURL string, options *clientv2.Options, interceptors ...clientv2.RequestInterceptor) T
 
-// createGQLClient takes a NewGQLClientFunc, endpoint and authToken
-// runs the NewGQLClientFunc
-// sets the authToken as a request header in the request interceptor
-// returns a GQLClient
+// createGQLClient takes a NewGQLClientFunc, endpoint and request headers, and
+// runs the NewGQLClientFunc, passing in the endpoint.
+// It also sets the request headers in the request interceptor.
+// And returns a GQLClient.
 func createGQLClient[T GQLClient](newGQLClientFunc NewGQLClientFunc[T], endpoint string, headers RequestHeaders) T {
 
 	requestInterceptor := func(ctx context.Context, req *http.Request, gqlInfo *clientv2.GQLRequestInfo, res interface{}, next clientv2.RequestInterceptorFunc) error {
@@ -50,15 +52,15 @@ func createGQLClient[T GQLClient](newGQLClientFunc NewGQLClientFunc[T], endpoint
 	return newGQLClientFunc(http.DefaultClient, endpoint, nil, requestInterceptor)
 }
 
-// RestClient defines the interface for the default http client
+// RestClient defines the interface for the default http client.
 type RestClient struct {
 	endpoint   string
 	headers    RequestHeaders
 	httpClient *http.Client
 }
 
-// NewRequest takes a method, uri, headers and body
-// if the request needs an empty body, like for a GET request, just pass in empty list of bytes
+// NewRequest takes a method, uri, request headers and body.
+// if the request needs an empty body, like for a GET request, just pass in an empty list of bytes.
 func (r *RestClient) NewRequest(method string, uri string, headers RequestHeaders, body []byte) (request *http.Request, err error) {
 	if r.endpoint == "" {
 		return nil, errors.New("rest client endpoint not set")
@@ -82,10 +84,12 @@ func (r *RestClient) NewRequest(method string, uri string, headers RequestHeader
 	return request, nil
 }
 
+// Do sends a http request and returns a http response.
 func (r *RestClient) Do(request *http.Request) (*http.Response, error) {
 	return r.httpClient.Do(request)
 }
 
+// ReadResponseJson reads the response body and unmarshals it into the given interface.
 func (r *RestClient) ReadResponseJson(response *http.Response, v any) error {
 	defer func(Body io.ReadCloser) {
 		_ = Body.Close()
@@ -103,13 +107,11 @@ func createRestClient(endpoint string, headers RequestHeaders) RestClient {
 	}
 }
 
-// NewGenericAPI takes a NewGQLClientFunc, endpoint, and authToken, and
-// returns an GenericAPI interface
+// NewGenericAPI takes a NewGQLClientFunc, a gqlEndpoint for the GQLClient, a restEndpoint for the RestClient, and request headers.
+// The request headers are set the same for both clients. NewGenericAPI returns an GenericAPI interface.
 // Example:
-// ```
-// api := NewGenericAPI[generated.GQLClient](generated.NewClient, "<endpoint>", "<authToken>")
-// api.GetGQLClient().GetUser(...)
-// ```
+//
+//	api := NewGenericAPI[generated.GQLClient](generated.NewClient, "<gqlEndpoint>", "<restEndpoint>", RequestHeaders{WithAuthToken("<authToken>")})
 func NewGenericAPI[T GQLClient](newGQLClientFunc NewGQLClientFunc[T], gqlEndpoint string, restEndpoint string, headers RequestHeaders) GenericAPI[T] {
 
 	return GenericAPI[T]{
@@ -118,14 +120,17 @@ func NewGenericAPI[T GQLClient](newGQLClientFunc NewGQLClientFunc[T], gqlEndpoin
 	}
 }
 
+// GetGQLClient returns the GQLClient.
 func (r GenericAPI[T]) GetGQLClient() T {
 	return r.GQLClient
 }
 
+// GetRestClient returns the RestClient.
 func (r GenericAPI[T]) GetRestClient() RestClient {
 	return r.RestClient
 }
 
+// ProcessGQLError takes an error returned by the GQLClient, improve it's message formatting and returns it.
 func (r GenericAPI[T]) ProcessGQLError(err error) error {
 	if handledError, ok := err.(*clientv2.ErrorResponse); ok {
 		msg := "handled error: "

api/generic_provider.go

@@ -1,8 +1,8 @@
 package api
 
-// GenericProvider is an interface for an api object.
-// The api object is expected to have a generated GQLClient and a default http RestClient.
-// The api object should implement a method to process a GQLError
+// GenericProvider is an interface for an api instance.
+// The api instance should have a generated GQLClient and a default http RestClient.
+// The api object should implement ProcessGQLError to process a GQLError
 type GenericProvider[T GQLClient] interface {
 	GetGQLClient() T
 	GetRestClient() RestClient

api/headers.go

@@ -1,16 +1,19 @@
 package api
 
-// WithAuthHeader returns a RequestHeader with the key "Authorization" and the value of the authToken
+// WithAuthHeader returns a RequestHeader with the key "Authorization" and the value of the authToken.
 func WithAuthHeader(authToken string) RequestHeader {
 	return RequestHeader{Key: "Authorization", Value: authToken}
 }
 
+// ContentType is an enum for the content type of a request.
 type ContentType string
 
 const (
+	// ContentTypeJson is the content type for a request with a json body in utf-8.
 	ContentTypeJson ContentType = "application/json; charset=UTF-8"
 )
 
+// WithContentType returns a RequestHeader with the key "Content-Type" and the string value of the contentType enum.
 func WithContentType(contentType ContentType) RequestHeader {
 	return RequestHeader{Key: "Content-Type", Value: string(contentType)}
 }

config/config.go

@@ -6,7 +6,7 @@ import (
 	"github.com/deploifai/sdk-go/credentials"
 )
 
-// Config provides the configuration for the service clients
+// Config provides the configuration for the service clients.
 type Config struct {
 	Credentials credentials.Provider
 	API         api.Provider
@@ -49,6 +49,7 @@ func (cs configs) ResolveConfig(ctx context.Context, resolvers []configResolver)
 	return cfg, nil
 }
 
+// LoadDefaultConfig loads the default configuration for the service clients.
 func LoadDefaultConfig(ctx context.Context, optFns ...func(*LoadOptions) error) (Config, error) {
 
 	var options LoadOptions

config/configs.go

@@ -5,8 +5,10 @@ import (
 	"github.com/deploifai/sdk-go/credentials"
 )
 
+// IConfig is an interface that all external configuration values must satisfy.
 type IConfig interface{}
 
+// configs is a slice of IConfig types.
 type configs []IConfig
 
 type loader func(context.Context, configs) (IConfig, error)

config/load_options.go

@@ -15,13 +15,15 @@ type LoadOptions struct {
 // LoadOptionsFunc is a type alias for LoadOptions functional option
 type LoadOptionsFunc func(*LoadOptions) error
 
+// WithCredentials is a functional option for setting the [LoadOptions.Credentials]
 func WithCredentials(v credentials.Provider) LoadOptionsFunc {
 	return func(o *LoadOptions) error {
 		o.Credentials = v
 		return nil
 	}
 }
 
+// WithAPI is a functional option for setting the [LoadOptions.API]
 func WithAPI(v api.Provider) LoadOptionsFunc {
 	return func(o *LoadOptions) error {
 		o.API = v

config/provider.go

@@ -6,6 +6,7 @@ import (
 	"github.com/deploifai/sdk-go/credentials"
 )
 
+// CredentialsProvider is an interface for retrieving an credentials.Provider
 type CredentialsProvider interface {
 	getCredentials(ctx context.Context) (credentials.Provider, bool, error)
 }

credentials/credentials.go

@@ -2,10 +2,13 @@ package credentials
 
 import "context"
 
+// Credentials holds the credentials needed to authenticate API requests.
 type Credentials struct {
 	AuthToken string
 }
 
+// Provider is the interface for any component which will provide
+// credentials.
 type Provider interface {
 	Retrieve() (Credentials, error)
 }
@@ -19,6 +22,7 @@ func (fn ProviderFunc) Retrieve(ctx context.Context) (Credentials, error) {
 	return fn(ctx)
 }
 
+// NewCredentials returns a new Credentials instance.
 func NewCredentials(authToken string) Credentials {
 	return Credentials{
 		AuthToken: authToken,

service/cloud_profile/create.go

@@ -5,6 +5,7 @@ import (
 	"github.com/deploifai/sdk-go/api/generated"
 )
 
+// Create creates a new cloud profile for the given account.
 func (c *Client) Create(ctx context.Context, whereAccount generated.AccountWhereUniqueInput, data generated.CloudProfileCreateInput) (cloudProfile generated.CloudProfileFragment, err error) {
 
 	responseData, err := c.options.API.GetGQLClient().CreateCloudProfile(ctx, whereAccount, data)