add variable and method comments

internal/metal/providers/emapi/client.go

@@ -25,12 +25,14 @@ const (
 	staffHeaderValue = "true"
 )
 
+// DefaultHTTPClient is the default http client used if no client is provided.
 var DefaultHTTPClient = &http.Client{
 	Timeout: defaultHTTPTimeout,
 }
 
 var _ providers.Provider = &Client{}
 
+// Client is the client to interact with the equinix metal api.
 type Client struct {
 	logger        *zap.SugaredLogger
 	httpClient    *http.Client
@@ -39,6 +41,8 @@ type Client struct {
 	consumerToken string
 }
 
+// Do executes the provided request.
+// If the out value is provided, the response will attempt to be json decoded.
 func (c *Client) Do(req *http.Request, out any) (*http.Response, error) {
 	if c.authToken != "" {
 		req.Header.Set(authHeader, c.authToken)
@@ -68,6 +72,7 @@ func (c *Client) Do(req *http.Request, out any) (*http.Response, error) {
 	return resp, nil
 }
 
+// DoRequest creates a new request from the provided parameters and executes the request.
 func (c *Client) DoRequest(ctx context.Context, method, path string, body io.Reader, out any) (*http.Response, error) {
 	path = strings.TrimPrefix(path, c.baseURL.Path)
 

internal/metal/providers/emapi/config.go

@@ -17,6 +17,7 @@ type Config struct {
 	ConsumerToken string
 }
 
+// Populated checks if any field has been populated.
 func (c Config) Populated() bool {
 	return c.AuthToken != "" || c.ConsumerToken != "" || c.BaseURL != ""
 }

internal/metal/providers/emapi/doc.go

@@ -0,0 +1,2 @@
+// Package emapi implement a metal provider which fetches details from the Equinix Metal API.
+package emapi

internal/metal/providers/emapi/errors.go

@@ -2,4 +2,5 @@ package emapi
 
 import "errors"
 
+// ErrBaseURLRequired is returned if no base url is provided.
 var ErrBaseURLRequired = errors.New("emapi base url required")

internal/metal/providers/emapi/memberships.go

@@ -4,10 +4,13 @@ import (
 	"go.equinixmetal.net/infra9-metal-bridge/internal/metal/models"
 )
 
+// Roles contains a list of roles.
 type Roles []string
 
+// Memberships contains a list of memberships
 type Memberships []*Membership
 
+// ToDetailsWithOrganizationDetails convers the memberships to generic membership models with organization details.
 func (m Memberships) ToDetailsWithOrganizationDetails(orgDetails *models.OrganizationDetails) []*models.Membership[models.OrganizationDetails] {
 	memberships := make([]*models.Membership[models.OrganizationDetails], len(m))
 
@@ -28,6 +31,7 @@ func (m Memberships) ToDetailsWithOrganizationDetails(orgDetails *models.Organiz
 	return memberships
 }
 
+// ToDetailsWithProjectDetails convers the memberships to generic membership models with project details.
 func (m Memberships) ToDetailsWithProjectDetails(projDetails *models.ProjectDetails) []*models.Membership[models.ProjectDetails] {
 	memberships := make([]*models.Membership[models.ProjectDetails], len(m))
 
@@ -48,6 +52,7 @@ func (m Memberships) ToDetailsWithProjectDetails(projDetails *models.ProjectDeta
 	return memberships
 }
 
+// Membership contains membership information.
 type Membership struct {
 	client *Client
 
@@ -57,6 +62,7 @@ type Membership struct {
 	User  *User  `json:"user"`
 }
 
+// ToDetailsWithOrganizationDetails convers the membership to generic membership model with organization details.
 func (m *Membership) ToDetailsWithOrganizationDetails(orgDetails *models.OrganizationDetails) *models.Membership[models.OrganizationDetails] {
 	if m.ID == "" {
 		return nil
@@ -70,6 +76,7 @@ func (m *Membership) ToDetailsWithOrganizationDetails(orgDetails *models.Organiz
 	}
 }
 
+// ToDetailsWithOrganizationDetails convers the membership to generic membership model with organization details.
 func (m *Membership) ToDetailsWithProjectDetails(projDetails *models.ProjectDetails) *models.Membership[models.ProjectDetails] {
 	if m.ID == "" {
 		return nil

internal/metal/providers/emapi/organizations.go

@@ -14,8 +14,10 @@ const (
 	organizationsPath = "/organizations"
 )
 
+// Organizations contains a list of organizations.
 type Organizations []*Organization
 
+// ToDetails converts to a generic model organization details.
 func (o Organizations) ToDetails() []*models.OrganizationDetails {
 	orgs := make([]*models.OrganizationDetails, len(o))
 
@@ -36,6 +38,7 @@ func (o Organizations) ToDetails() []*models.OrganizationDetails {
 	return orgs
 }
 
+// Organization contains organization information.
 type Organization struct {
 	client *Client
 
@@ -47,6 +50,7 @@ type Organization struct {
 	Projects    Projects    `json:"projects"`
 }
 
+// ToDetails converts the object to a generic orgnization details.
 func (o *Organization) ToDetails() *models.OrganizationDetails {
 	var id string
 
@@ -69,6 +73,7 @@ func (o *Organization) ToDetails() *models.OrganizationDetails {
 	return details
 }
 
+// getOrganizationWithMemberships fetches an organization from the equinix metal api with membership user information.
 func (c *Client) getOrganizationWithMemberships(ctx context.Context, id string) (*Organization, error) {
 	var org Organization
 
@@ -80,6 +85,7 @@ func (c *Client) getOrganizationWithMemberships(ctx context.Context, id string)
 	return &org, nil
 }
 
+// GetOrganizationDetails fetches the organization id provided with its memberships.
 func (c *Client) GetOrganizationDetails(ctx context.Context, id gidx.PrefixedID) (*models.OrganizationDetails, error) {
 	org, err := c.getOrganizationWithMemberships(ctx, id.String()[gidx.PrefixPartLength+1:])
 	if err != nil {

internal/metal/providers/emapi/projects.go

@@ -14,8 +14,10 @@ const (
 	projectsPath = "/projects"
 )
 
+// Projects contains a list of projects.
 type Projects []*Project
 
+// ToDetails converts the objects to generic project details.
 func (p Projects) ToDetails() []*models.ProjectDetails {
 	projects := make([]*models.ProjectDetails, len(p))
 
@@ -36,6 +38,7 @@ func (p Projects) ToDetails() []*models.ProjectDetails {
 	return projects
 }
 
+// Project contains project information.
 type Project struct {
 	client *Client
 
@@ -47,6 +50,7 @@ type Project struct {
 	Organization *Organization `json:"organization"`
 }
 
+// ToDetails converts the project to generic project details.
 func (p *Project) ToDetails() *models.ProjectDetails {
 	var id string
 
@@ -69,6 +73,7 @@ func (p *Project) ToDetails() *models.ProjectDetails {
 	return details
 }
 
+// getProjectWithMemberships fetches the provided project with membership information.
 func (c *Client) getProjectWithMemberships(ctx context.Context, id string) (*Project, error) {
 	var project Project
 
@@ -80,6 +85,7 @@ func (c *Client) getProjectWithMemberships(ctx context.Context, id string) (*Pro
 	return &project, nil
 }
 
+// GetProjectDetails fetchs the provided project id with membership information.
 func (c *Client) GetProjectDetails(ctx context.Context, id gidx.PrefixedID) (*models.ProjectDetails, error) {
 	project, err := c.getProjectWithMemberships(ctx, id.String()[gidx.PrefixPartLength+1:])
 	if err != nil {

internal/metal/providers/emapi/users.go

@@ -14,8 +14,10 @@ const (
 	usersPath = "/users"
 )
 
+// Users contains a list of users.
 type Users []*User
 
+// ToDetails converts the objects to generic user details.
 func (u Users) ToDetails() []*models.UserDetails {
 	users := make([]*models.UserDetails, len(u))
 
@@ -36,6 +38,7 @@ func (u Users) ToDetails() []*models.UserDetails {
 	return users
 }
 
+// User contains user information.
 type User struct {
 	client *Client
 
@@ -46,6 +49,7 @@ type User struct {
 	Projects Projects `json:"projects"`
 }
 
+// ToDetails converts the user to generic user details.
 func (u *User) ToDetails() *models.UserDetails {
 	var id string
 
@@ -65,6 +69,7 @@ func (u *User) ToDetails() *models.UserDetails {
 	}
 }
 
+// getUser fetches the provided user.
 func (c *Client) getUser(ctx context.Context, id string) (*User, error) {
 	var user User
 
@@ -76,6 +81,7 @@ func (c *Client) getUser(ctx context.Context, id string) (*User, error) {
 	return &user, nil
 }
 
+// GetUserDetails fetches the provided user id.
 func (c *Client) GetUserDetails(ctx context.Context, id gidx.PrefixedID) (*models.UserDetails, error) {
 	user, err := c.getUser(ctx, id.String()[gidx.PrefixPartLength+1:])
 	if err != nil {
@@ -85,10 +91,12 @@ func (c *Client) GetUserDetails(ctx context.Context, id gidx.PrefixedID) (*model
 	return user.ToDetails(), nil
 }
 
+// GetUserOrganizationRole returns collaborator for all organizations.
 func (c *Client) GetUserOrganizationRole(ctx context.Context, userID, orgID gidx.PrefixedID) (string, error) {
 	return "collaborator", nil
 }
 
+// GetUserProjectRole returns collaborator for all projects.
 func (c *Client) GetUserProjectRole(ctx context.Context, userID, projectID gidx.PrefixedID) (string, error) {
 	return "collaborator", nil
 }