add variable and method comments

internal/permissions/roles.go

@@ -9,25 +9,31 @@ import (
 	"golang.org/x/exp/slices"
 )
 
+// ResourceRoleCreate is the role create request.
 type ResourceRoleCreate struct {
 	Actions []string `json:"actions"`
 }
 
+// ResourceRoleCreateResponse is the role creation response.
 type ResourceRoleCreateResponse struct {
 	ID string `json:"id"`
 }
 
+// ResourceRoleDeleteResponse is the role deletion response.
 type ResourceRoleDeleteResponse struct {
 	Success bool `json:"success"`
 }
 
+// ResourceRoles is a listg of resource roles.
 type ResourceRoles []ResourceRole
 
+// ResourceRole contains the role id and its actions.
 type ResourceRole struct {
 	ID      gidx.PrefixedID `json:"id"`
 	Actions []string        `json:"actions"`
 }
 
+// CreateRole creates a role on the given resource id with the provided actions.
 func (c *Client) CreateRole(ctx context.Context, resourceID gidx.PrefixedID, actions []string) (gidx.PrefixedID, error) {
 	path := fmt.Sprintf("/api/v1/resources/%s/roles", resourceID.String())
 
@@ -52,6 +58,7 @@ func (c *Client) CreateRole(ctx context.Context, resourceID gidx.PrefixedID, act
 	return roleID, nil
 }
 
+// DeleteRole deletes the provided role.
 func (c *Client) DeleteRole(ctx context.Context, roleID gidx.PrefixedID) error {
 	path := fmt.Sprintf("/api/v1/roles/%s", roleID.String())
 
@@ -68,6 +75,7 @@ func (c *Client) DeleteRole(ctx context.Context, roleID gidx.PrefixedID) error {
 	return nil
 }
 
+// ListResourceRoles fetches all roles assigned to the provided resource.
 func (c *Client) ListResourceRoles(ctx context.Context, resourceID gidx.PrefixedID) (ResourceRoles, error) {
 	path := fmt.Sprintf("/api/v1/resources/%s/roles", resourceID.String())
 
@@ -82,6 +90,7 @@ func (c *Client) ListResourceRoles(ctx context.Context, resourceID gidx.Prefixed
 	return response.Data, nil
 }
 
+// FindResourceRoleByActions fetches roles assigned to the provided resource and finds the first role where the actions match the provided actions.
 func (c *Client) FindResourceRoleByActions(ctx context.Context, resourceID gidx.PrefixedID, actions []string) (ResourceRole, error) {
 	roles, err := c.ListResourceRoles(ctx, resourceID)
 	if err != nil {