chore(docs): Clean up public doc strings on client, factory and top-level components. (#196)

Michael Ng · web-flow · commit 2caaa0dc1ae2 · 2019-11-27T09:44:20.000-08:00
diff --git a/optimizely.go b/optimizely.go
@@ -21,7 +21,7 @@ import (
 	"github.com/optimizely/go-sdk/pkg/entities"
 )
 
-// Client returns an OptimizelyClient instantitated with the given key and options
+// Client returns an OptimizelyClient instantiated with the given key and options
 func Client(sdkKey string, options ...client.OptionFunc) (*client.OptimizelyClient, error) {
 	factory := &client.OptimizelyFactory{
 		SDKKey: sdkKey,
diff --git a/pkg/client/client.go b/pkg/client/client.go
@@ -42,7 +42,8 @@ type OptimizelyClient struct {
 	executionCtx utils.ExecutionCtx
 }
 
-// Activate returns the key of the variation the user is bucketed into and sends an impression event to the Optimizely log endpoint
+// Activate returns the key of the variation the user is bucketed into and queues up an impression event to be sent to
+// the Optimizely log endpoint for results processing.
 func (o *OptimizelyClient) Activate(experimentKey string, userContext entities.UserContext) (result string, err error) {
 
 	defer func() {
@@ -77,7 +78,8 @@ func (o *OptimizelyClient) Activate(experimentKey string, userContext entities.U
 	return result, err
 }
 
-// IsFeatureEnabled returns true if the feature is enabled for the given user
+// IsFeatureEnabled returns true if the feature is enabled for the given user. If the user is part of a feature test
+// then an impression event will be queued up to be sent to the Optimizely log endpoint for results processing.
 func (o *OptimizelyClient) IsFeatureEnabled(featureKey string, userContext entities.UserContext) (result bool, err error) {
 
 	defer func() {
@@ -122,7 +124,8 @@ func (o *OptimizelyClient) IsFeatureEnabled(featureKey string, userContext entit
 	return result, err
 }
 
-// GetEnabledFeatures returns an array containing the keys of all features in the project that are enabled for the given user.
+// GetEnabledFeatures returns an array containing the keys of all features in the project that are enabled for the given
+// user. For features tests, impression events will be queued up to be sent to the Optimizely log endpoint for results processing.
 func (o *OptimizelyClient) GetEnabledFeatures(userContext entities.UserContext) (enabledFeatures []string, err error) {
 
 	defer func() {
@@ -156,7 +159,7 @@ func (o *OptimizelyClient) GetEnabledFeatures(userContext entities.UserContext)
 	return enabledFeatures, err
 }
 
-// GetFeatureVariableBoolean returns boolean feature variable value
+// GetFeatureVariableBoolean returns the feature variable value of type bool associated with the given feature and variable keys.
 func (o *OptimizelyClient) GetFeatureVariableBoolean(featureKey, variableKey string, userContext entities.UserContext) (value bool, err error) {
 
 	val, valueType, err := o.GetFeatureVariable(featureKey, variableKey, userContext)
@@ -170,7 +173,7 @@ func (o *OptimizelyClient) GetFeatureVariableBoolean(featureKey, variableKey str
 	return convertedValue, err
 }
 
-// GetFeatureVariableDouble returns double feature variable value
+// GetFeatureVariableDouble returns the feature variable value of type double associated with the given feature and variable keys.
 func (o *OptimizelyClient) GetFeatureVariableDouble(featureKey, variableKey string, userContext entities.UserContext) (value float64, err error) {
 
 	val, valueType, err := o.GetFeatureVariable(featureKey, variableKey, userContext)
@@ -184,7 +187,7 @@ func (o *OptimizelyClient) GetFeatureVariableDouble(featureKey, variableKey stri
 	return convertedValue, err
 }
 
-// GetFeatureVariableInteger returns integer feature variable value
+// GetFeatureVariableInteger returns the feature variable value of type int associated with the given feature and variable keys.
 func (o *OptimizelyClient) GetFeatureVariableInteger(featureKey, variableKey string, userContext entities.UserContext) (value int, err error) {
 
 	val, valueType, err := o.GetFeatureVariable(featureKey, variableKey, userContext)
@@ -198,7 +201,7 @@ func (o *OptimizelyClient) GetFeatureVariableInteger(featureKey, variableKey str
 	return convertedValue, err
 }
 
-// GetFeatureVariableString returns string feature variable value
+// GetFeatureVariableString returns the feature variable value of type string associated with the given feature and variable keys.
 func (o *OptimizelyClient) GetFeatureVariableString(featureKey, variableKey string, userContext entities.UserContext) (value string, err error) {
 
 	value, valueType, err := o.GetFeatureVariable(featureKey, variableKey, userContext)
@@ -211,7 +214,7 @@ func (o *OptimizelyClient) GetFeatureVariableString(featureKey, variableKey stri
 	return value, err
 }
 
-// GetFeatureVariable returns feature as a string along with it's associated type
+// GetFeatureVariable returns feature variable as a string along with it's associated type.
 func (o *OptimizelyClient) GetFeatureVariable(featureKey, variableKey string, userContext entities.UserContext) (value string, valueType entities.VariableType, err error) {
 
 	featureDecisionContext, featureDecision, err := o.getFeatureDecision(featureKey, variableKey, userContext)
@@ -230,7 +233,7 @@ func (o *OptimizelyClient) GetFeatureVariable(featureKey, variableKey string, us
 	return variable.DefaultValue, variable.Type, err
 }
 
-// GetAllFeatureVariables returns all the variables for a given feature along with the enabled state
+// GetAllFeatureVariables returns all the variables for a given feature along with the enabled state.
 func (o *OptimizelyClient) GetAllFeatureVariables(featureKey string, userContext entities.UserContext) (enabled bool, variableMap map[string]string, err error) {
 
 	variableMap = make(map[string]string)
@@ -263,7 +266,7 @@ func (o *OptimizelyClient) GetAllFeatureVariables(featureKey string, userContext
 	return enabled, variableMap, err
 }
 
-// GetVariation returns the key of the variation the user is bucketed into
+// GetVariation returns the key of the variation the user is bucketed into. Does not generate impression events.
 func (o *OptimizelyClient) GetVariation(experimentKey string, userContext entities.UserContext) (result string, err error) {
 
 	defer func() {
@@ -294,7 +297,8 @@ func (o *OptimizelyClient) GetVariation(experimentKey string, userContext entiti
 	return result, err
 }
 
-// Track take and event key with event tags and if the event is part of the config, send to events backend.
+// Track generates a conversion event with the given event key if it exists and queues it up to be sent to the Optimizely
+// log endpoint for results processing.
 func (o *OptimizelyClient) Track(eventKey string, userContext entities.UserContext, eventTags map[string]interface{}) (err error) {
 
 	defer func() {
@@ -427,7 +431,7 @@ func (o *OptimizelyClient) getExperimentDecision(experimentKey string, userConte
 	return decisionContext, experimentDecision, err
 }
 
-// GetProjectConfig returns the current ProjectConfig or nil if the instance is not valid
+// GetProjectConfig returns the current ProjectConfig or nil if the instance is not valid.
 func (o *OptimizelyClient) GetProjectConfig() (projectConfig pkg.ProjectConfig, err error) {
 
 	projectConfig, err = o.ConfigManager.GetConfig()
@@ -438,7 +442,7 @@ func (o *OptimizelyClient) GetProjectConfig() (projectConfig pkg.ProjectConfig,
 	return projectConfig, nil
 }
 
-// Close closes the Optimizely instance and stops any ongoing tasks from its children components
+// Close closes the Optimizely instance and stops any ongoing tasks from its children components.
 func (o *OptimizelyClient) Close() {
 	o.executionCtx.TerminateAndWait()
 }
diff --git a/pkg/client/factory.go b/pkg/client/factory.go
@@ -28,7 +28,7 @@ import (
 	"github.com/optimizely/go-sdk/pkg/utils"
 )
 
-// OptimizelyFactory is used to construct an instance of the OptimizelyClient
+// OptimizelyFactory is used to customize and construct an instance of the OptimizelyClient.
 type OptimizelyFactory struct {
 	SDKKey   string
 	Datafile []byte
@@ -41,10 +41,10 @@ type OptimizelyFactory struct {
 	overrideStore      decision.ExperimentOverrideStore
 }
 
-// OptionFunc is used to provide custom client configuration to the OptimizelyFactory
+// OptionFunc is used to provide custom client configuration to the OptimizelyFactory.
 type OptionFunc func(*OptimizelyFactory)
 
-// Client instantiates a new OptimizelyClient with the given options
+// Client instantiates a new OptimizelyClient with the given options.
 func (f OptimizelyFactory) Client(clientOptions ...OptionFunc) (*OptimizelyClient, error) {
 	// extract options
 	for _, opt := range clientOptions {
@@ -112,58 +112,58 @@ func (f OptimizelyFactory) Client(clientOptions ...OptionFunc) (*OptimizelyClien
 	return appClient, nil
 }
 
-// WithPollingConfigManager sets polling config manager on a client
+// WithPollingConfigManager sets polling config manager on a client.
 func WithPollingConfigManager(sdkKey string, pollingInterval time.Duration, initDataFile []byte) OptionFunc {
 	return func(f *OptimizelyFactory) {
 		f.configManager = config.NewPollingProjectConfigManager(sdkKey, config.InitialDatafile(initDataFile),
 			config.PollingInterval(pollingInterval))
 	}
 }
 
-// WithPollingConfigManagerRequester sets polling config manager on a client
+// WithPollingConfigManagerRequester sets polling config manager on a client.
 func WithPollingConfigManagerRequester(requester utils.Requester, pollingInterval time.Duration, initDataFile []byte) OptionFunc {
 	return func(f *OptimizelyFactory) {
 		f.configManager = config.NewPollingProjectConfigManager("", config.InitialDatafile(initDataFile),
 			config.PollingInterval(pollingInterval), config.Requester(requester))
 	}
 }
 
-// WithConfigManager sets polling config manager on a client
+// WithConfigManager sets polling config manager on a client.
 func WithConfigManager(configManager pkg.ProjectConfigManager) OptionFunc {
 	return func(f *OptimizelyFactory) {
 		f.configManager = configManager
 	}
 }
 
-// WithCompositeDecisionService sets decision service on a client
+// WithCompositeDecisionService sets decision service on a client.
 func WithCompositeDecisionService(sdkKey string) OptionFunc {
 	return func(f *OptimizelyFactory) {
 		f.decisionService = decision.NewCompositeService(sdkKey)
 	}
 }
 
-// WithDecisionService sets decision service on a client
+// WithDecisionService sets decision service on a client.
 func WithDecisionService(decisionService decision.Service) OptionFunc {
 	return func(f *OptimizelyFactory) {
 		f.decisionService = decisionService
 	}
 }
 
-// WithUserProfileService sets the user profile service on the decision service
+// WithUserProfileService sets the user profile service on the decision service.
 func WithUserProfileService(userProfileService decision.UserProfileService) OptionFunc {
 	return func(f *OptimizelyFactory) {
 		f.userProfileService = userProfileService
 	}
 }
 
-// WithExperimentOverrides sets the experiment override store on the decision service
+// WithExperimentOverrides sets the experiment override store on the decision service.
 func WithExperimentOverrides(overrideStore decision.ExperimentOverrideStore) OptionFunc {
 	return func(f *OptimizelyFactory) {
 		f.overrideStore = overrideStore
 	}
 }
 
-// WithBatchEventProcessor sets event processor on a client
+// WithBatchEventProcessor sets event processor on a client.
 func WithBatchEventProcessor(batchSize, queueSize int, flushInterval time.Duration) OptionFunc {
 	return func(f *OptimizelyFactory) {
 		f.eventProcessor = event.NewBatchEventProcessor(event.WithBatchSize(batchSize),
@@ -178,14 +178,14 @@ func WithEventProcessor(eventProcessor event.Processor) OptionFunc {
 	}
 }
 
-// WithExecutionContext allows user to pass in their own execution context to override the default one in the client
+// WithExecutionContext allows user to pass in their own execution context to override the default one in the client.
 func WithExecutionContext(executionContext utils.ExecutionCtx) OptionFunc {
 	return func(f *OptimizelyFactory) {
 		f.executionCtx = executionContext
 	}
 }
 
-// StaticClient returns a client initialized with a static project config
+// StaticClient returns a client initialized with a static project config.
 func (f OptimizelyFactory) StaticClient() (*OptimizelyClient, error) {
 	var configManager pkg.ProjectConfigManager
 
diff --git a/pkg/config/polling_manager.go b/pkg/config/polling_manager.go
@@ -45,7 +45,8 @@ const DatafileURLTemplate = "https://cdn.optimizely.com/datafiles/%s.json"
 
 var cmLogger = logging.GetLogger("PollingConfigManager")
 
-// PollingProjectConfigManager maintains a dynamic copy of the project config
+// PollingProjectConfigManager maintains a dynamic copy of the project config by continuously polling for the datafile
+// from the Optimizely CDN at a given (configurable) interval.
 type PollingProjectConfigManager struct {
 	requester           utils.Requester
 	pollingInterval     time.Duration
@@ -59,7 +60,7 @@ type PollingProjectConfigManager struct {
 	projectConfig pkg.ProjectConfig
 }
 
-// OptionFunc is a type to a proper func
+// OptionFunc is used to provide custom configuration to the PollingProjectConfigManager.
 type OptionFunc func(*PollingProjectConfigManager)
 
 // Requester is an optional function, sets a passed requester
diff --git a/pkg/decision/composite_service.go b/pkg/decision/composite_service.go
@@ -29,14 +29,14 @@ import (
 
 var csLogger = logging.GetLogger("CompositeDecisionService")
 
-// CompositeService is the entrypoint into the decision service. It provides out of the box decision making for Features and Experiments.
+// CompositeService is the entry-point into the decision service. It provides out of the box decision making for Features and Experiments.
 type CompositeService struct {
 	compositeExperimentService ExperimentService
 	compositeFeatureService    FeatureService
 	notificationCenter         notification.Center
 }
 
-// CSOptionFunc is used to pass config options into the CompositeService
+// CSOptionFunc is used to pass custom config options into the CompositeService.
 type CSOptionFunc func(*CompositeService)
 
 // WithCompositeExperimentService sets the composite experiment service on the CompositeService
diff --git a/pkg/event/factory_test.go b/pkg/event/factory_test.go
@@ -129,11 +129,11 @@ func TestCreateAndSendImpressionEvent(t *testing.T) {
 
 	processor.ProcessEvent(impressionUserEvent)
 
-	assert.Equal(t, 1, processor.EventsCount())
+	assert.Equal(t, 1, processor.eventsCount())
 
 	time.Sleep(100 * time.Millisecond)
 
-	assert.Equal(t, 0, processor.EventsCount())
+	assert.Equal(t, 0, processor.eventsCount())
 }
 
 func TestCreateAndSendConversionEvent(t *testing.T) {
@@ -147,11 +147,11 @@ func TestCreateAndSendConversionEvent(t *testing.T) {
 
 	processor.ProcessEvent(conversionUserEvent)
 
-	assert.Equal(t, 1, processor.EventsCount())
+	assert.Equal(t, 1, processor.eventsCount())
 
 	time.Sleep(100 * time.Millisecond)
 
-	assert.Equal(t, 0, processor.EventsCount())
+	assert.Equal(t, 0, processor.eventsCount())
 }
 
 func TestCreateConversionEventRevenue(t *testing.T) {
diff --git a/pkg/event/processor.go b/pkg/event/processor.go
diff --git a/pkg/event/processor_test.go b/pkg/event/processor_test.go
diff --git a/pkg/interface.go b/pkg/interface.go

Original file line number	Diff line number	Diff line change
`@@ -21,7 +21,7 @@ import (`
`21`	`21`	`"github.com/optimizely/go-sdk/pkg/entities"`
`22`	`22`	`)`
`23`	`23`
`24`		`-// Client returns an OptimizelyClient instantitated with the given key and options`
	`24`	`+// Client returns an OptimizelyClient instantiated with the given key and options`
`25`	`25`	`func Client(sdkKey string, options ...client.OptionFunc) (*client.OptimizelyClient, error) {`
`26`	`26`	`factory := &client.OptimizelyFactory{`
`27`	`27`	`SDKKey: sdkKey,`
Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ import (`
`28`	`28`	`"github.com/optimizely/go-sdk/pkg/utils"`
`29`	`29`	`)`
`30`	`30`
`31`		`-// OptimizelyFactory is used to construct an instance of the OptimizelyClient`
	`31`	`+// OptimizelyFactory is used to customize and construct an instance of the OptimizelyClient.`
`32`	`32`	`type OptimizelyFactory struct {`
`33`	`33`	`SDKKey string`
`34`	`34`	`Datafile []byte`
`@@ -41,10 +41,10 @@ type OptimizelyFactory struct {`
`41`	`41`	`overrideStore decision.ExperimentOverrideStore`
`42`	`42`	`}`
`43`	`43`
`44`		`-// OptionFunc is used to provide custom client configuration to the OptimizelyFactory`
	`44`	`+// OptionFunc is used to provide custom client configuration to the OptimizelyFactory.`
`45`	`45`	`type OptionFunc func(*OptimizelyFactory)`
`46`	`46`
`47`		`-// Client instantiates a new OptimizelyClient with the given options`
	`47`	`+// Client instantiates a new OptimizelyClient with the given options.`
`48`	`48`	`func (f OptimizelyFactory) Client(clientOptions ...OptionFunc) (*OptimizelyClient, error) {`
`49`	`49`	`// extract options`
`50`	`50`	`for _, opt := range clientOptions {`
`@@ -112,58 +112,58 @@ func (f OptimizelyFactory) Client(clientOptions ...OptionFunc) (*OptimizelyClien`
`112`	`112`	`return appClient, nil`
`113`	`113`	`}`
`114`	`114`
`115`		`-// WithPollingConfigManager sets polling config manager on a client`
	`115`	`+// WithPollingConfigManager sets polling config manager on a client.`
`116`	`116`	`func WithPollingConfigManager(sdkKey string, pollingInterval time.Duration, initDataFile []byte) OptionFunc {`
`117`	`117`	`return func(f *OptimizelyFactory) {`
`118`	`118`	`f.configManager = config.NewPollingProjectConfigManager(sdkKey, config.InitialDatafile(initDataFile),`
`119`	`119`	`config.PollingInterval(pollingInterval))`
`120`	`120`	`}`
`121`	`121`	`}`
`122`	`122`
`123`		`-// WithPollingConfigManagerRequester sets polling config manager on a client`
	`123`	`+// WithPollingConfigManagerRequester sets polling config manager on a client.`
`124`	`124`	`func WithPollingConfigManagerRequester(requester utils.Requester, pollingInterval time.Duration, initDataFile []byte) OptionFunc {`
`125`	`125`	`return func(f *OptimizelyFactory) {`
`126`	`126`	`f.configManager = config.NewPollingProjectConfigManager("", config.InitialDatafile(initDataFile),`
`127`	`127`	`config.PollingInterval(pollingInterval), config.Requester(requester))`
`128`	`128`	`}`
`129`	`129`	`}`
`130`	`130`
`131`		`-// WithConfigManager sets polling config manager on a client`
	`131`	`+// WithConfigManager sets polling config manager on a client.`
`132`	`132`	`func WithConfigManager(configManager pkg.ProjectConfigManager) OptionFunc {`
`133`	`133`	`return func(f *OptimizelyFactory) {`
`134`	`134`	`f.configManager = configManager`
`135`	`135`	`}`
`136`	`136`	`}`
`137`	`137`
`138`		`-// WithCompositeDecisionService sets decision service on a client`
	`138`	`+// WithCompositeDecisionService sets decision service on a client.`
`139`	`139`	`func WithCompositeDecisionService(sdkKey string) OptionFunc {`
`140`	`140`	`return func(f *OptimizelyFactory) {`
`141`	`141`	`f.decisionService = decision.NewCompositeService(sdkKey)`
`142`	`142`	`}`
`143`	`143`	`}`
`144`	`144`
`145`		`-// WithDecisionService sets decision service on a client`
	`145`	`+// WithDecisionService sets decision service on a client.`
`146`	`146`	`func WithDecisionService(decisionService decision.Service) OptionFunc {`
`147`	`147`	`return func(f *OptimizelyFactory) {`
`148`	`148`	`f.decisionService = decisionService`
`149`	`149`	`}`
`150`	`150`	`}`
`151`	`151`
`152`		`-// WithUserProfileService sets the user profile service on the decision service`
	`152`	`+// WithUserProfileService sets the user profile service on the decision service.`
`153`	`153`	`func WithUserProfileService(userProfileService decision.UserProfileService) OptionFunc {`
`154`	`154`	`return func(f *OptimizelyFactory) {`
`155`	`155`	`f.userProfileService = userProfileService`
`156`	`156`	`}`
`157`	`157`	`}`
`158`	`158`
`159`		`-// WithExperimentOverrides sets the experiment override store on the decision service`
	`159`	`+// WithExperimentOverrides sets the experiment override store on the decision service.`
`160`	`160`	`func WithExperimentOverrides(overrideStore decision.ExperimentOverrideStore) OptionFunc {`
`161`	`161`	`return func(f *OptimizelyFactory) {`
`162`	`162`	`f.overrideStore = overrideStore`
`163`	`163`	`}`
`164`	`164`	`}`
`165`	`165`
`166`		`-// WithBatchEventProcessor sets event processor on a client`
	`166`	`+// WithBatchEventProcessor sets event processor on a client.`
`167`	`167`	`func WithBatchEventProcessor(batchSize, queueSize int, flushInterval time.Duration) OptionFunc {`
`168`	`168`	`return func(f *OptimizelyFactory) {`
`169`	`169`	`f.eventProcessor = event.NewBatchEventProcessor(event.WithBatchSize(batchSize),`
`@@ -178,14 +178,14 @@ func WithEventProcessor(eventProcessor event.Processor) OptionFunc {`
`178`	`178`	`}`
`179`	`179`	`}`
`180`	`180`
`181`		`-// WithExecutionContext allows user to pass in their own execution context to override the default one in the client`
	`181`	`+// WithExecutionContext allows user to pass in their own execution context to override the default one in the client.`
`182`	`182`	`func WithExecutionContext(executionContext utils.ExecutionCtx) OptionFunc {`
`183`	`183`	`return func(f *OptimizelyFactory) {`
`184`	`184`	`f.executionCtx = executionContext`
`185`	`185`	`}`
`186`	`186`	`}`
`187`	`187`
`188`		`-// StaticClient returns a client initialized with a static project config`
	`188`	`+// StaticClient returns a client initialized with a static project config.`
`189`	`189`	`func (f OptimizelyFactory) StaticClient() (*OptimizelyClient, error) {`
`190`	`190`	`var configManager pkg.ProjectConfigManager`
`191`	`191`