nit: Added comments in publicly exposed functions (#31)

mnoman09 · NomanShoaib · msohailhussain · web-flow · commit 372dea47074b · 2022-10-05T14:41:52.000-07:00
* Removed unused import
Added proper comments on publicaly exposed functions

* Nit Spaces

Co-authored-by: mnoman09 &lt;m.nomanshoaib09@gmail.com&gt;
Co-authored-by: Mirza Sohail Hussain &lt;mirza.sohailhussain@gmail.com&gt;
diff --git a/lib/optimizely_flutter_sdk.dart b/lib/optimizely_flutter_sdk.dart
@@ -79,111 +79,170 @@ class OptimizelyFlutterSdk {
   ///  The activate call will conditionally activate an experiment for a user based on the provided experiment key and a randomized hash of the provided user ID.
   ///  If the user satisfies audience conditions for the experiment and the experiment is valid and running, the function returns the variation the user is bucketed into.
   ///  Otherwise, activate returns empty variationKey. Make sure that your code adequately deals with the case when the experiment is not activated (e.g. execute the default variation).
+  ///
+  /// Takes [experimentKey] The key of the experiment to set with the forced variation.
+  /// Takes [userId] The ID of the user to force into the variation.
+  /// Takes [attributes] A [Map] of custom key-value string pairs specifying attributes for the user.
+  /// Returns [ActivateResponse] The key of the variation where the user is bucketed, or `empty variationKey` if the user
+  ///                        doesn't qualify for the experiment.
   Future<ActivateResponse> activate(String experimentKey, String userId,
       [Map<String, dynamic> attributes = const {}]) async {
     return await OptimizelyClientWrapper.activate(
         _sdkKey, experimentKey, userId, attributes);
   }
 
   /// Get variation for experiment and user ID with user attributes.
+  ///
+  /// Takes [experimentKey] The key of the experiment to set with the forced variation.
+  /// Takes [userId] The ID of the user to force into the variation.
+  /// Takes [attributes] A [Map] of custom key-value string pairs specifying attributes for the user.
+  /// Returns [GetVariationResponse] The key of the variation where the user is bucketed, or `empty variationKey` if the user
+  ///                        doesn't qualify for the experiment.
   Future<GetVariationResponse> getVariation(String experimentKey, String userId,
       [Map<String, dynamic> attributes = const {}]) async {
     return await OptimizelyClientWrapper.getVariation(
         _sdkKey, experimentKey, userId, attributes);
   }
 
   /// Get forced variation for experiment and user ID.
+  ///
+  /// Takes [experimentKey] The key of the experiment to set with the forced variation.
+  /// Takes [userId] The ID of the user to force into the variation.
+  /// Returns [GetVariationResponse] The key of the variation where the user is bucketed, or `empty variationKey` if the user
+  ///                        doesn't qualify for the experiment.
   Future<GetVariationResponse> getForcedVariation(
       String experimentKey, String userId) async {
     return await OptimizelyClientWrapper.getForcedVariation(
         _sdkKey, experimentKey, userId);
   }
 
   /// Set forced variation for experiment and user ID to variationKey.
+  ///
+  /// Takes [experimentKey] The key of the experiment to set with the forced variation.
+  /// Takes [userId] The ID of the user to force into the variation.
+  /// Takes [variationKey] The key of the forced variation.
+  /// Returns [BaseResponse] success as `true` if the user was successfully forced into a variation, `false` if the `experimentKey`
+  ///                        isn't in the project file or the `variationKey` isn't in the experiment.
   Future<BaseResponse> setForcedVariation(String experimentKey, String userId,
       [String variationKey = ""]) async {
     return await OptimizelyClientWrapper.setForcedVariation(
         _sdkKey, experimentKey, userId, variationKey);
   }
 
-  /// Returns a snapshot of the current project configuration.
+  /// Returns [OptimizelyConfigResponse] a snapshot of the current project configuration.
   Future<OptimizelyConfigResponse> getOptimizelyConfig() async {
     return await OptimizelyClientWrapper.getOptimizelyConfig(_sdkKey);
   }
 
   /// Creates a context of the user for which decision APIs will be called.
   ///
-  /// A user context will only be created successfully when the SDK is fully configured using initializeClient.
+  /// NOTE: A user context will only be created successfully when the SDK is fully configured using initializeClient.
+  ///
+  /// Takes [userId] the [String] user ID to be used for bucketing.
+  /// Takes [attributes] An Optional [Map] of attribute names to current user attribute values.
+  /// Returns An [OptimizelyUserContext] associated with this OptimizelyClient.
   Future<OptimizelyUserContext?> createUserContext(String userId,
       [Map<String, dynamic> attributes = const {}]) async {
     return await OptimizelyClientWrapper.createUserContext(
         _sdkKey, userId, attributes);
   }
 
   /// Checks if eventHandler are Closeable and calls close on them.
+  ///
+  /// Returns [BaseResponse] A object containing success result or reason of failure.
   Future<BaseResponse> close() async {
     return await OptimizelyClientWrapper.close(_sdkKey);
   }
 
   /// Allows user to listen to supported Activate notifications.
+  ///
+  /// Takes [callback] A [ActivateNotificationCallback] notification handler to be added.
+  /// Returns [CancelListening] A callback function that allows the user to remove the added notification listener.
   Future<CancelListening> addActivateNotificationListener(
       ActivateNotificationCallback callback) async {
     return await _addActivateNotificationListener(callback);
   }
 
   /// Allows user to listen to supported Decision notifications.
+  ///
+  /// Takes [callback] A [DecisionNotificationCallback] notification handler to be added.
+  /// Returns [CancelListening] A callback function that allows the user to remove the added notification listener.
   Future<CancelListening> addDecisionNotificationListener(
       DecisionNotificationCallback callback) async {
     return await _addDecisionNotificationListener(callback);
   }
 
   /// Allows user to listen to supported Track notifications.
+  ///
+  /// Takes [callback] A [TrackNotificationCallback] notification handler to be added.
+  /// Returns [CancelListening] A callback function that allows the user to remove the added notification listener.
   Future<CancelListening> addTrackNotificationListener(
       TrackNotificationCallback callback) async {
     return await _addTrackNotificationListener(callback);
   }
 
   /// Allows user to listen to supported LogEvent notifications.
+  ///
+  /// Takes [callback] A [LogEventNotificationCallback] notification handler to be added.
+  /// Returns [CancelListening] A callback function that allows the user to remove the added notification listener.
   Future<CancelListening> addLogEventNotificationListener(
       LogEventNotificationCallback callback) async {
     return await _addLogEventNotificationListener(callback);
   }
 
   /// Allows user to listen to supported Project Config Update notifications.
+  ///
+  /// Takes [callback] A [MultiUseCallback] notification handler to be added.
+  /// Returns [CancelListening] A callback function that allows the user to remove the added notification listener.
   Future<CancelListening> addUpdateConfigNotificationListener(
       MultiUseCallback callback) async {
     return await _addConfigUpdateNotificationListener(callback);
   }
 
   /// Allows user to listen to supported Activate notifications.
+  ///
+  /// Takes [callback] A [ActivateNotificationCallback] notification handler to be added.
+  /// Returns [CancelListening] A callback function that allows the user to remove the added notification listener.
   Future<CancelListening> _addActivateNotificationListener(
       ActivateNotificationCallback callback) async {
     return await OptimizelyClientWrapper.addActivateNotificationListener(
         _sdkKey, callback);
   }
 
   /// Allows user to listen to supported Decision notifications.
+  ///
+  /// Takes [callback] A [DecisionNotificationCallback] notification handler to be added.
+  /// Returns [CancelListening] A callback function that allows the user to remove the added notification listener.
   Future<CancelListening> _addDecisionNotificationListener(
       DecisionNotificationCallback callback) async {
     return await OptimizelyClientWrapper.addDecisionNotificationListener(
         _sdkKey, callback);
   }
 
   /// Allows user to listen to supported Track notifications.
+  ///
+  /// Takes [callback] A [TrackNotificationCallback] notification handler to be added.
+  /// Returns [CancelListening] A callback function that allows the user to remove the added notification listener.
   Future<CancelListening> _addTrackNotificationListener(
       TrackNotificationCallback callback) async {
     return await OptimizelyClientWrapper.addTrackNotificationListener(
         _sdkKey, callback);
   }
 
   /// Allows user to listen to supported LogEvent notifications.
+  ///
+  /// Takes [callback] A [LogEventNotificationCallback] notification handler to be added.
+  /// Returns [CancelListening] A callback function that allows the user to remove the added notification listener.
   Future<CancelListening> _addLogEventNotificationListener(
       LogEventNotificationCallback callback) async {
     return await OptimizelyClientWrapper.addLogEventNotificationListener(
         _sdkKey, callback);
   }
 
   /// Allows user to listen to supported Project Config Update notifications.
+  ///
+  /// Takes [callback] A [MultiUseCallback] notification handler to be added.
+  /// Returns [CancelListening] A callback function that allows the user to remove the added notification listener.
   Future<CancelListening> _addConfigUpdateNotificationListener(
       MultiUseCallback callback) async {
     return await OptimizelyClientWrapper.addConfigUpdateNotificationListener(
diff --git a/lib/src/optimizely_client_wrapper.dart b/lib/src/optimizely_client_wrapper.dart
@@ -23,7 +23,6 @@ import 'package:optimizely_flutter_sdk/src/data_objects/activate_response.dart';
 import 'package:optimizely_flutter_sdk/src/data_objects/base_response.dart';
 import 'package:optimizely_flutter_sdk/src/data_objects/get_variation_response.dart';
 import 'package:optimizely_flutter_sdk/src/data_objects/optimizely_config_response.dart';
-import 'package:optimizely_flutter_sdk/src/user_context/optimizely_user_context.dart';
 import 'package:optimizely_flutter_sdk/src/utils/constants.dart';
 import 'package:optimizely_flutter_sdk/src/utils/utils.dart';
 
diff --git a/lib/src/user_context/optimizely_user_context.dart b/lib/src/user_context/optimizely_user_context.dart
@@ -52,7 +52,7 @@ class OptimizelyUserContext {
 
   OptimizelyUserContext(this._sdkKey, this._userContextId, this._channel);
 
-  /// Returns userId for the user context.
+  /// Returns [GetUserIdResponse] object containing userId for the user context.
   Future<GetUserIdResponse> getUserId() async {
     final result = Map<String, dynamic>.from(
         await _channel.invokeMethod(Constants.getUserIdMethod, {
@@ -62,7 +62,7 @@ class OptimizelyUserContext {
     return GetUserIdResponse(result);
   }
 
-  /// Returns attributes for the user context.
+  /// Returns [GetAttributesResponse] object containing attributes for the user context.
   Future<GetAttributesResponse> getAttributes() async {
     final result = Map<String, dynamic>.from(
         await _channel.invokeMethod(Constants.getAttributesMethod, {
@@ -73,6 +73,9 @@ class OptimizelyUserContext {
   }
 
   /// Sets attributes for the user context.
+  ///
+  /// Takes [attributes] A [Map] of custom key-value string pairs specifying attributes for the user.
+  /// Returns [BaseResponse]
   Future<BaseResponse> setAttributes(Map<String, dynamic> attributes) async {
     final result = Map<String, dynamic>.from(
         await _channel.invokeMethod(Constants.setAttributesMethod, {
@@ -84,6 +87,10 @@ class OptimizelyUserContext {
   }
 
   /// Tracks an event.
+  ///
+  /// Takes [eventKey] The event name.
+  /// Optional [eventTags] A [Map] of event tag names to event tag values.
+  /// Returns [BaseResponse]
   Future<BaseResponse> trackEvent(String eventKey,
       [Map<String, dynamic> eventTags = const {}]) async {
     final result = Map<String, dynamic>.from(
@@ -97,6 +104,10 @@ class OptimizelyUserContext {
   }
 
   /// Returns a decision result for a given flag key and a user context, which contains all data required to deliver the flag or experiment.
+  ///
+  /// Takes [key] A flag key for which a decision will be made.
+  /// Optional [options] A set of [OptimizelyDecideOption] for decision-making.
+  /// Returns [DecideResponse] A decision result.
   Future<DecideResponse> decide(String key,
       [Set<OptimizelyDecideOption> options = const {}]) async {
     // passing key as an array since decide has a single generic implementation which takes array of keys as an argument
@@ -105,13 +116,20 @@ class OptimizelyUserContext {
   }
 
   /// Returns a key-map of decision results for multiple flag keys and a user context.
+  ///
+  /// Takes [keys] A [List] of flag keys for which decisions will be made.
+  /// Optional [options] A set of [OptimizelyDecideOption] for decision-making.
+  /// Returns [DecideForKeysResponse] All decision results mapped by flag keys.
   Future<DecideForKeysResponse> decideForKeys(List<String> keys,
       [Set<OptimizelyDecideOption> options = const {}]) async {
     final result = await _decide(keys, options);
     return DecideForKeysResponse(result);
   }
 
   /// Returns a key-map of decision results for all active flag keys.
+  ///
+  /// Optional [options] A set of [OptimizelyDecideOption] for decision-making.
+  /// Returns [DecideForKeysResponse] All decision results mapped by flag keys.
   Future<DecideForKeysResponse> decideAll(
       [Set<OptimizelyDecideOption> options = const {}]) async {
     final result = await _decide([], options);
@@ -134,6 +152,10 @@ class OptimizelyUserContext {
   }
 
   /// Sets the forced decision for a given decision context.
+  ///
+  /// Takes [context] The [OptimizelyDecisionContext] containing flagKey and ruleKey.
+  /// Takes [decision] The [OptimizelyForcedDecision] containing the variationKey.
+  /// Returns [BaseResponse]
   Future<BaseResponse> setForcedDecision(OptimizelyDecisionContext context,
       OptimizelyForcedDecision decision) async {
     Map<String, dynamic> request = {
@@ -151,6 +173,9 @@ class OptimizelyUserContext {
   }
 
   /// Returns the forced decision for a given decision context.
+  ///
+  /// Takes [context] The [OptimizelyDecisionContext] containing flagKey and ruleKey.
+  /// Returns [GetForcedDecisionResponse] containing a variationKey for a given forced decision
   Future<GetForcedDecisionResponse> getForcedDecision(
       OptimizelyDecisionContext context) async {
     Map<String, dynamic> request = {
@@ -168,6 +193,9 @@ class OptimizelyUserContext {
   }
 
   /// Removes the forced decision for a given decision context.
+  ///
+  /// Takes [context] The [OptimizelyDecisionContext] containing flagKey and ruleKey.
+  /// Returns [BaseResponse]
   Future<BaseResponse> removeForcedDecision(
       OptimizelyDecisionContext context) async {
     Map<String, dynamic> request = {
@@ -184,6 +212,8 @@ class OptimizelyUserContext {
   }
 
   /// Removes all forced decisions bound to this user context.
+  ///
+  /// Returns [BaseResponse]
   Future<BaseResponse> removeAllForcedDecisions() async {
     final result = Map<String, dynamic>.from(
         await _channel.invokeMethod(Constants.removeAllForcedDecisions, {
