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 {