Add more comments

cmd/config.go

@@ -7,6 +7,7 @@ import (
 )
 
 // config defines the external configuration required for the connector to run.
+// You can add additional fields here and have them automatically mapped to any additional command line flags
 type config struct {
 	cli.BaseConfig `mapstructure:",squash"` // Puts the base config options in the same place as the connector options
 }

cmd/main.go

@@ -17,6 +17,10 @@ import (
 
 var version = "dev"
 
+// This is the primary entrypoint for the connector. It uses the SDK to standardize command line flags.
+// By using `cli.NewCmd()` from the SDK allows the SDK to be in charge of the lifecycle of your connector logic.
+// You are able to add additional flags and update the configuration in case your connector needs more input from the user
+// in order to run.
 func main() {
 	ctx := context.Background()
 

pkg/client/client.go

@@ -41,6 +41,8 @@ type Project struct {
 	GroupAssignments []string
 }
 
+// This is a simple example client. While this client would normally be responsible for communicating with an upstream
+// API, for this demo the client is only working with in-memory data.
 type Client struct{}
 
 // ListUsers returns all the users from the database

pkg/connector/connector.go

@@ -14,6 +14,7 @@ type Demo struct {
 	client *client.Client
 }
 
+// ResourceSyncers returns a ResourceSyncer for each resource type that should be synced from the upstream service.
 func (d *Demo) ResourceSyncers(ctx context.Context) []connectorbuilder.ResourceSyncer {
 	return []connectorbuilder.ResourceSyncer{
 		newUserBuilder(d.client),

pkg/connector/groups.go

@@ -19,6 +19,8 @@ func (o *groupBuilder) ResourceType(ctx context.Context) *v2.ResourceType {
 	return groupResourceType
 }
 
+// List returns all the groups from the database as resource objects
+// Groups include the GroupTrait because they have the 'shape' of the well known Group type
 func (o *groupBuilder) List(ctx context.Context, parentResourceID *v2.ResourceId, pToken *pagination.Token) ([]*v2.Resource, string, annotations.Annotations, error) {
 	groups, err := o.client.ListGroups(ctx)
 	if err != nil {

pkg/connector/projects.go

@@ -19,6 +19,8 @@ func (o *projectBuilder) ResourceType(ctx context.Context) *v2.ResourceType {
 	return projectResourceType
 }
 
+// List returns all the projects from the database as resource objects
+// Projects don't include any traits because they don't match the 'shape' of any well known types.
 func (o *projectBuilder) List(ctx context.Context, parentResourceID *v2.ResourceId, pToken *pagination.Token) ([]*v2.Resource, string, annotations.Annotations, error) {
 	projects, err := o.client.ListProjects(ctx)
 	if err != nil {

pkg/connector/resource_types.go

@@ -4,25 +4,29 @@ import (
 	v2 "github.com/conductorone/baton-sdk/pb/c1/connector/v2"
 )
 
+// The user resource type is for all user objects from the database
 var userResourceType = &v2.ResourceType{
 	Id:          "user",
 	DisplayName: "User",
 	Traits:      []v2.ResourceType_Trait{v2.ResourceType_TRAIT_USER},
 }
 
+// The group resource type is for all group objects from the database
 var groupResourceType = &v2.ResourceType{
 	Id:          "group",
 	DisplayName: "Group",
 	Traits:      []v2.ResourceType_Trait{v2.ResourceType_TRAIT_GROUP},
 }
 
+// The role resource type is for all role objects from the database
 var roleResourceType = &v2.ResourceType{
 	Id:          "role",
 	DisplayName: "Role",
 	Traits:      []v2.ResourceType_Trait{v2.ResourceType_TRAIT_ROLE},
 }
 
-// Projects don't match any of the well-known resource traits
+// The project resource type is for all project objects from the database
+// Projects don't match any of the well-known resource traits.
 var projectResourceType = &v2.ResourceType{
 	Id:          "project",
 	DisplayName: "Project",

pkg/connector/roles.go

@@ -19,7 +19,8 @@ func (o *roleBuilder) ResourceType(ctx context.Context) *v2.ResourceType {
 	return roleResourceType
 }
 
-// List returns a slice of resources, one for each role returned by the client
+// List returns all the roles from the database as resource objects
+// Roles include the role trait because they have the 'shape' of the well known Role type
 func (o *roleBuilder) List(ctx context.Context, parentResourceID *v2.ResourceId, pToken *pagination.Token) ([]*v2.Resource, string, annotations.Annotations, error) {
 	roles, err := o.client.ListRoles(ctx)
 	if err != nil {

pkg/connector/users.go

@@ -18,6 +18,8 @@ func (o *userBuilder) ResourceType(ctx context.Context) *v2.ResourceType {
 	return userResourceType
 }
 
+// List returns all the users from the database as resource objects.
+// Users include a UserTrait because they are the 'shape' of a standard user
 func (o *userBuilder) List(ctx context.Context, parentResourceID *v2.ResourceId, pToken *pagination.Token) ([]*v2.Resource, string, annotations.Annotations, error) {
 	users, err := o.client.ListUsers(ctx)
 	if err != nil {