feat: Enhance Posthog SDK documentation methods (#282)

Author: deandreamatias

lib/src/posthog.dart

@@ -72,6 +72,20 @@ class Posthog {
   @internal
   String? get currentScreen => _currentScreen;
 
+  /// Can associate events with specific users
+  ///
+  /// - [userId] A unique identifier for your user. Typically either their email or database ID.
+  /// - [userProperties] the user properties, set as a "$set" property,
+  /// - [userPropertiesSetOnce] the user properties to set only once, set as a "$set_once" property.
+  ///
+  /// **Example:**
+  /// ```dart
+  /// await Posthog().identify(
+  ///   userId: emailController.text,
+  ///   userProperties: {"name": "Peter Griffin", "email": "peter@familyguy.com"},
+  ///   userPropertiesSetOnce: {"date_of_first_log_in": "2024-03-01"}
+  /// );
+  /// ```
   Future<void> identify({
     required String userId,
     Map<String, Object>? userProperties,
@@ -82,6 +96,29 @@ class Posthog {
           userProperties: userProperties,
           userPropertiesSetOnce: userPropertiesSetOnce);
 
+  /// Captures events.
+  /// Docs https://posthog.com/docs/product-analytics/user-properties
+  ///
+  /// We recommend using a [object] [verb] format for your event names,
+  /// where [object] is the entity that the behavior relates to,
+  /// and [verb] is the behavior itself.
+  /// For example, project created, user signed up, or invite sent.
+  ///
+  /// - [eventName] name of event
+  /// - [properties] the custom properties
+  /// - [userProperties] the user properties, set as a "$set" property,
+  /// - [userPropertiesSetOnce] the user properties to set only once, set as a "$set_once" property.
+  ///
+  /// **Example**
+  /// ```dart
+  ///   await Posthog().capture(
+  ///    eventName: 'user_signed_up',
+  ///    properties: {
+  ///      'login_type': 'email',
+  ///      'is_free_trial': true
+  ///    }
+  ///   );
+  /// ```
   Future<void> capture({
     required String eventName,
     Map<String, Object>? properties,
@@ -104,6 +141,10 @@ class Posthog {
     );
   }
 
+  /// Captures a screen view event
+  ///
+  /// - [screenName] the screen title
+  /// - [properties] the custom properties
   Future<void> screen({
     required String screenName,
     Map<String, Object>? properties,
@@ -115,39 +156,83 @@ class Posthog {
     );
   }
 
+  /// Creates an alias for the user.
+  /// Docs https://posthog.com/docs/product-analytics/identify#alias-assigning-multiple-distinct-ids-to-the-same-user
+  ///
+  /// - [alias] the alias
   Future<void> alias({
     required String alias,
   }) =>
       _posthog.alias(
         alias: alias,
       );
 
+  /// Returns the registered `distinctId` property
   Future<String> getDistinctId() => _posthog.getDistinctId();
 
+  /// Resets all the cached properties including the `distinctId`.
+  ///
+  /// The SDK will behave as its been [setup] for the first time
   Future<void> reset() => _posthog.reset();
 
+  /// Disable data collection for a user
   Future<void> disable() {
     // Uninstall Flutter-specific integrations when disabling
     _uninstallFlutterIntegrations();
 
     return _posthog.disable();
   }
 
+  /// Enable data collection for a user
   Future<void> enable() => _posthog.enable();
 
+  /// Check if the user has opted out of data collection
   Future<bool> isOptOut() => _posthog.isOptOut();
 
+  /// Enable or disable verbose logs about the inner workings of the SDK.
+  ///
+  /// - [enabled] whether to enable or disable debug logs
   Future<void> debug(bool enabled) => _posthog.debug(enabled);
 
+  /// Register a property to always be sent with all the following events until you call
+  /// [unregister] with the same key.
+  ///
+  /// - [key] the Key
+  /// - [value] the Value
   Future<void> register(String key, Object value) =>
       _posthog.register(key, value);
 
+  /// Unregisters the previously set property to be sent with all the following events
+  ///
+  /// [key] the Key
   Future<void> unregister(String key) => _posthog.unregister(key);
 
+  /// Returns if a feature flag is enabled, the feature flag must be a Boolean
+  ///
+  /// Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments
+  ///
+  /// - [key] the Key of the feature
   Future<bool> isFeatureEnabled(String key) => _posthog.isFeatureEnabled(key);
 
+  /// Reloads the feature flags
   Future<void> reloadFeatureFlags() => _posthog.reloadFeatureFlags();
 
+  /// Creates a group.
+  /// Docs https://posthog.com/docs/product-analytics/group-analytics
+  ///
+  /// - [groupType] the Group type
+  /// - [groupKey] the Group key
+  /// - [groupProperties] the Group properties, set as a "$group_set" property.
+  ///
+  /// **Example:**
+  /// ```dart
+  /// await Posthog().group(
+  ///  groupType: "company",
+  ///  groupKey: "company_id_in_your_db",
+  ///  groupProperties: {
+  ///    "name": "ACME Corp"
+  /// });
+  /// ```
   Future<void> group({
     required String groupType,
     required String groupKey,
@@ -197,9 +282,9 @@ class Posthog {
 
   /// Captures exceptions with optional custom properties
   ///
-  /// [error] - The error/exception to capture
-  /// [stackTrace] - Optional stack trace (if not provided, current stack trace will be used)
-  /// [properties] - Optional custom properties to attach to the exception event
+  /// - [error] - The error/exception to capture
+  /// - [stackTrace] - Optional stack trace (if not provided, current stack trace will be used)
+  /// - [properties] - Optional custom properties to attach to the exception event
   Future<void> captureException(
           {required Object error,
           StackTrace? stackTrace,
@@ -210,9 +295,9 @@ class Posthog {
   /// Captures runZonedGuarded exceptions with optional custom properties
   /// https://api.flutter.dev/flutter/dart-async/runZonedGuarded.html
   ///
-  /// [error] - The error/exception to capture
-  /// [stackTrace] - Optional stack trace (if not provided, current stack trace will be used)
-  /// [properties] - Optional custom properties to attach to the exception event
+  /// - [error] - The error/exception to capture
+  /// - [stackTrace] - Optional stack trace (if not provided, current stack trace will be used)
+  /// - [properties] - Optional custom properties to attach to the exception event
   Future<void> captureRunZonedGuardedError(
       {required Object error,
       StackTrace? stackTrace,
@@ -237,6 +322,7 @@ class Posthog {
     return _posthog.close();
   }
 
+  /// Returns the session Id if a session is active
   Future<String?> getSessionId() => _posthog.getSessionId();
 
   Posthog._internal();