Merge pull request #553 from Instabug/chore/enhance-inline-code-doc

Enhance inline code comments of APM related classes

Author: AndrewAminInstabug

lib/src/utils/screen_loading/instabug_capture_screen_loading.dart

@@ -4,15 +4,37 @@ import 'package:instabug_flutter/src/utils/instabug_montonic_clock.dart';
 import 'package:instabug_flutter/src/utils/screen_loading/screen_loading_manager.dart';
 import 'package:instabug_flutter/src/utils/screen_loading/screen_loading_trace.dart';
 
+/// A widget that tracks and reports screen loading times to Instabug.
+///
+/// This widget wraps around a child widget and measures the time taken
+/// for the screen to fully render. The recorded loading time is reported
+/// using the [ScreenLoadingManager].
+///
+/// ## Usage
+/// ```dart
+/// InstabugCaptureScreenLoading(
+///   screenName: "HomeScreen",
+///   child: HomeScreenWidget(),
+/// )
+/// ```
 class InstabugCaptureScreenLoading extends StatefulWidget {
+  /// A unique identifier for the widget used internally for debugging purposes.
   static const tag = "InstabugCaptureScreenLoading";
 
+  /// Creates an instance of [InstabugCaptureScreenLoading].
+  ///
+  /// Requires [screenName] to identify the screen being tracked and [child]
+  /// which represents the UI component to be rendered.
   const InstabugCaptureScreenLoading({
     Key? key,
     required this.screenName,
     required this.child,
   }) : super(key: key);
+
+  /// The UI component whose loading time is being measured.
   final Widget child;
+
+  /// The name of the screen being monitored for loading performance.
   final String screenName;
 
   @override
@@ -22,9 +44,16 @@ class InstabugCaptureScreenLoading extends StatefulWidget {
 
 class _InstabugCaptureScreenLoadingState
     extends State<InstabugCaptureScreenLoading> {
+  /// Trace object that records screen loading details.
   ScreenLoadingTrace? trace;
+
+  /// Timestamp in microseconds when the widget is created.
   final startTimeInMicroseconds = IBGDateTime.I.now().microsecondsSinceEpoch;
+
+  /// Monotonic timestamp in microseconds for more precise duration tracking.
   final startMonotonicTimeInMicroseconds = InstabugMonotonicClock.I.now;
+
+  /// Stopwatch to measure screen loading time.
   final stopwatch = Stopwatch()..start();
 
   @override
@@ -38,7 +67,7 @@ class _InstabugCaptureScreenLoadingState
 
     ScreenLoadingManager.I.startScreenLoadingTrace(trace!);
 
-    // to maintain supported versions prior to Flutter 3.0.0
+    // Ensures compatibility with Flutter versions before 3.0.0
     // ignore: invalid_null_aware_operator
     WidgetsBinding.instance?.addPostFrameCallback((_) {
       stopwatch.stop();

lib/src/utils/screen_loading/screen_loading_manager.dart

@@ -9,7 +9,10 @@ import 'package:instabug_flutter/src/utils/screen_loading/screen_loading_trace.d
 import 'package:instabug_flutter/src/utils/screen_loading/ui_trace.dart';
 import 'package:meta/meta.dart';
 
-/// @nodoc
+/// Manages screen loading traces and UI traces for performance monitoring.
+///
+/// This class handles the tracking of screen loading times and UI transitions,
+/// providing an interface for Instabug APM to capture and report performance metrics.
 @internal
 class ScreenLoadingManager {
   ScreenLoadingManager._();
@@ -21,25 +24,33 @@ class ScreenLoadingManager {
 
   static ScreenLoadingManager _instance = ScreenLoadingManager._();
 
+  /// Returns the singleton instance of [ScreenLoadingManager].
   static ScreenLoadingManager get instance => _instance;
 
   /// Shorthand for [instance]
   static ScreenLoadingManager get I => instance;
+
+  /// Logging tag for debugging purposes.
   static const tag = "ScreenLoadingManager";
+
+  /// Stores the current UI trace.
   UiTrace? currentUiTrace;
+
+  /// Stores the current screen loading trace.
   ScreenLoadingTrace? currentScreenLoadingTrace;
 
-  /// @nodoc
+  /// Stores prematurely ended traces for debugging purposes.
   @internal
   final List<ScreenLoadingTrace> prematurelyEndedTraces = [];
 
+  /// Allows setting a custom instance for testing.
   @visibleForTesting
   // ignore: use_setters_to_change_properties
   static void setInstance(ScreenLoadingManager instance) {
     _instance = instance;
   }
 
-  /// @nodoc
+  /// Resets the flag indicating a screen loading trace has started.
   @internal
   void resetDidStartScreenLoading() {
     // Allows starting a new screen loading capture trace in the same ui trace (without navigating out and in to the same screen)
@@ -59,9 +70,8 @@ class ScreenLoadingManager {
     );
   }
 
-  /// @nodoc
+  /// Checks if the Instabug SDK is built before calling API methods.
   Future<bool> _checkInstabugSDKBuilt(String apiName) async {
-    // Check if Instabug SDK is Built
     final isInstabugSDKBuilt = await Instabug.isBuilt();
     if (!isInstabugSDKBuilt) {
       InstabugLogger.I.e(
@@ -73,7 +83,7 @@ class ScreenLoadingManager {
     return isInstabugSDKBuilt;
   }
 
-  /// @nodoc
+  /// Resets the flag indicating a screen loading trace has been reported.
   @internal
   void resetDidReportScreenLoading() {
     // Allows reporting a new screen loading capture trace in the same ui trace even if one was reported before by resetting the flag which is used for checking.
@@ -84,7 +94,7 @@ class ScreenLoadingManager {
     );
   }
 
-  /// @nodoc
+  /// Starts a new UI trace with a given screen name.
   @internal
   void resetDidExtendScreenLoading() {
     // Allows reporting a new screen loading capture trace in the same ui trace even if one was reported before by resetting the flag which is used for checking.
@@ -176,7 +186,7 @@ class ScreenLoadingManager {
     }
   }
 
-  /// @nodoc
+  /// Starts a screen loading trace.
   @internal
   Future<void> startScreenLoadingTrace(ScreenLoadingTrace trace) async {
     try {
@@ -225,7 +235,7 @@ class ScreenLoadingManager {
     }
   }
 
-  /// @nodoc
+  /// Reports the input [ScreenLoadingTrace] to the native side.
   @internal
   Future<void> reportScreenLoading(ScreenLoadingTrace? trace) async {
     try {