Doc/update struct member doc (#30)

* Update struct member comments for Release

* Add comments to Space struct members

* Add a comment for Plan->AvailableSpaces

* Update space and cluster comment on URI/description

* Slug -> path

* Lint updated files

bonsai/cluster.go

@@ -34,7 +34,7 @@ type ClusterStats struct {
 
 // ClusterAccess holds information about connecting to the cluster.
 type ClusterAccess struct {
-	// Host name of the cluster
+	// Host name of the cluster.
 	Host string `json:"host"`
 	// HTTP Port the cluster is running on.
 	Port int `json:"port"`
@@ -67,19 +67,20 @@ const (
 	ClusterStateUpdatingPlan   ClusterState = "UPDATING PLAN"
 )
 
-// Cluster represents a subscription cluster.
+// Cluster represents a single cluster on your account.
 type Cluster struct {
 	// Slug represents a unique, machine-readable name for the cluster.
 	// A cluster slug is based its name at creation, to which a random integer
 	// is concatenated.
 	Slug string `json:"slug"`
 	// Name is the human-readable name of the cluster.
 	Name string `json:"name"`
-	// URI is a machine-readable name for the cluster.
+	// URI is a link to additional information about this cluster.
 	URI string `json:"uri"`
 
 	// Plan holds some information about the cluster's current subscription plan.
 	Plan Plan `json:"plan"`
+
 	// Release holds some information about the cluster's current release.
 	Release Release `json:"release"`
 
@@ -178,7 +179,7 @@ type ClusterCreateOpts struct {
 	// The slug of the Plan that the new cluster will be configured for.
 	// Use the [PlanClient.All] method to view a list of all Plans available.
 	Plan string `json:"plan,omitempty"`
-	// The slug of the Space where the new cluster should be deployed to.
+	// The path of the Space where the new cluster should be deployed to.
 	// Use the [SpaceClient.All] method to view a list of all Spaces.
 	Space string `json:"space,omitempty"`
 	// The Search Service Release that the new cluster will use.
@@ -282,7 +283,7 @@ func (c *ClusterClient) list(ctx context.Context, opt clusterListOpts) (
 	return results.Clusters, resp, nil
 }
 
-// All lists all Clusters from the Clusters API.
+// All lists all active clusters on your account.
 func (c *ClusterClient) All(ctx context.Context) ([]Cluster, error) {
 	var (
 		err  error

bonsai/plan.go

@@ -43,7 +43,9 @@ type planAllResponse struct {
 	// A collection of search release slugs available for the plan. Additional
 	// information about a release can be retrieved from the Releases API.
 	AvailableReleases []string `json:"available_releases"`
-	AvailableSpaces   []string `json:"available_spaces"`
+	// A collection of Space paths available for the plan. Additional
+	// information about a space can be retrieved from the Spaces API.
+	AvailableSpaces []string `json:"available_spaces"`
 
 	// A URI to retrieve more information about this Plan.
 	URI string `json:"uri,omitempty"`

bonsai/release.go

@@ -12,13 +12,18 @@ import (
 
 const ReleaseAPIBasePath = "/releases"
 
-// Release is a placeholder for now.
+// Release is a version of Elasticsearch available to the account.
 type Release struct {
-	Name        string `json:"name,omitempty"`
-	Slug        string `json:"slug,omitempty"`
+	// The name for the release.
+	Name string `json:"name,omitempty"`
+	// The machine-readable name for the deployment.
+	Slug string `json:"slug,omitempty"`
+	// The service type of the deployment - for example, "elasticsearch".
 	ServiceType string `json:"service_type,omitempty"`
-	Version     string `json:"version,omitempty"`
-	MultiTenant *bool  `json:"multitenant,omitempty"`
+	// The version of the release.
+	Version string `json:"version,omitempty"`
+	// Whether the release is available on multitenant deployments.
+	MultiTenant *bool `json:"multitenant,omitempty"`
 
 	// A URI to retrieve more information about this Release.
 	URI string `json:"uri,omitempty"`

bonsai/space.go

@@ -17,20 +17,28 @@ const (
 // CloudProvider contains details about the cloud provider and region
 // attributes.
 type CloudProvider struct {
+	// A machine-readable name for the cloud provider in which this space is
+	// deployed.
 	Provider string `json:"provider"`
-	Region   string `json:"region"`
+	// A machine-readable name for the geographic region of the server group.
+	Region string `json:"region"`
 }
 
 // Space represents the server groups and geographic regions available to their
 // account, where clusters may be provisioned.
 type Space struct {
-	Path           string         `json:"path"`
-	PrivateNetwork *bool          `json:"private_network,omitempty"`
-	Cloud          *CloudProvider `json:"cloud,omitempty"`
+	// A machine-readable name for the server group.
+	Path string `json:"path"`
+	// Indicates whether the space is isolated and inaccessible from the
+	// public Internet. A VPC connection will be needed to communicate
+	// with a private cluster.
+	PrivateNetwork *bool `json:"private_network,omitempty"`
+	// Details about the cloud provider and region attributes.
+	Cloud *CloudProvider `json:"cloud,omitempty"`
 
 	// The geographic region in which the cluster is running.
 	Region string `json:"region,omitempty"`
-	// A URI to retrieve more information about this Release.
+	// A URI to retrieve more information about this Space.
 	URI string `json:"uri,omitempty"`
 }
 
@@ -125,7 +133,7 @@ func (c *SpaceClient) All(ctx context.Context) ([]Space, error) {
 		return allResults, fmt.Errorf("client.all failed: %w", err)
 	}
 
-	return allResults, err
+	return allResults, err //nolint:nolintlint
 }
 
 //nolint:dupl // Allow duplicated code blocks in code paths that may change