Clean up on dart docs across all dart files under lib (#142)

* Clean up across all dart files under lib

* Fix format

* Apply suggestions from code review

Co-authored-by: Christopher Fujino <[email protected]>

---------

Co-authored-by: Christopher Fujino <[email protected]>

Author: eliasyishak

pkgs/unified_analytics/lib/src/analytics.dart

@@ -27,10 +27,13 @@ import 'utils.dart';
 
 abstract class Analytics {
   /// The default factory constructor that will return an implementation
-  /// of the [Analytics] abstract class using the [LocalFileSystem]
+  /// of the [Analytics] abstract class using the [LocalFileSystem].
   ///
   /// If [enableAsserts] is set to `true`, then asserts for GA4 limitations
-  /// will be enabled
+  /// will be enabled.
+  ///
+  /// [flutterChannel] and [flutterVersion] are nullable in case the client
+  /// using this package is unable to resolve those values.
   factory Analytics({
     required DashTool tool,
     required String dartVersion,
@@ -83,10 +86,13 @@ abstract class Analytics {
 
   /// Factory constructor to return the [AnalyticsImpl] class with
   /// Google Analytics credentials that point to a test instance and
-  /// not the production instance where live data will be sent
+  /// not the production instance where live data will be sent.
   ///
   /// By default, [enableAsserts] is set to `true` to check against
-  /// GA4 limitations
+  /// GA4 limitations.
+  ///
+  /// [flutterChannel] and [flutterVersion] are nullable in case the client
+  /// using this package is unable to resolve those values.
   factory Analytics.development({
     required DashTool tool,
     required String dartVersion,
@@ -142,22 +148,22 @@ abstract class Analytics {
   }
 
   /// Factory constructor to return the [AnalyticsImpl] class with a
-  /// [MemoryFileSystem] to use for testing
+  /// [MemoryFileSystem] to use for testing.
   @visibleForTesting
   factory Analytics.test({
     required DashTool tool,
     required Directory homeDirectory,
     required String measurementId,
     required String apiSecret,
-    String? flutterChannel,
-    String? flutterVersion,
     required String dartVersion,
-    int toolsMessageVersion = kToolsMessageVersion,
-    String toolsMessage = kToolsMessage,
     required FileSystem fs,
     required DevicePlatform platform,
+    String? flutterChannel,
+    String? flutterVersion,
     SurveyHandler? surveyHandler,
     GAClient? gaClient,
+    int toolsMessageVersion = kToolsMessageVersion,
+    String toolsMessage = kToolsMessage,
   }) =>
       AnalyticsImpl(
         tool: tool,
@@ -179,57 +185,57 @@ abstract class Analytics {
       );
 
   /// Retrieves the consent message to prompt users with on first
-  /// run or when the message has been updated
+  /// run or when the message has been updated.
   String get getConsentMessage;
 
-  /// Returns true if it is OK to send an analytics message.   Do not cache,
+  /// Returns true if it is OK to send an analytics message. Do not cache,
   /// as this depends on factors that can change, such as the configuration
   /// file contents.
   bool get okToSend;
 
   /// Returns a map object with all of the tools that have been parsed
-  /// out of the configuration file
+  /// out of the configuration file.
   Map<String, ToolInfo> get parsedTools;
 
-  /// Boolean that lets the client know if they should display the message
+  /// Boolean that lets the client know if they should display the message.
   bool get shouldShowMessage;
 
-  /// Boolean indicating whether or not telemetry is enabled
+  /// Boolean indicating whether or not telemetry is enabled.
   bool get telemetryEnabled;
 
   /// Returns a map representation of the [UserProperty] for the [Analytics]
   /// instance.
   ///
-  /// This is what will get sent to Google Analytics with every request
+  /// This is what will get sent to Google Analytics with every request.
   Map<String, Map<String, Object?>> get userPropertyMap;
 
   /// Method to be invoked by the client using this package to confirm
   /// that the client has shown the message and that it can be added to
-  /// the config file and start sending events the next time it starts up
+  /// the config file and start sending events the next time it starts up.
   void clientShowedMessage();
 
-  /// Call this method when the tool using this package is closed
+  /// Call this method when the tool using this package is closed.
   ///
   /// Prevents the tool from hanging when if there are still requests
-  /// that need to be sent off
+  /// that need to be sent off.
   void close();
 
-  /// Method to fetch surveys from the specified endpoint [kContextualSurveyUrl]
+  /// Method to fetch surveys from the endpoint [kContextualSurveyUrl].
   ///
   /// Any survey that is returned by this method has already passed
-  /// the survey conditions specified in the remote survey metadata file
+  /// the survey conditions specified in the remote survey metadata file.
   ///
   /// If the method returns an empty list, then there are no surveys to be
-  /// shared with the user
+  /// shared with the user.
   Future<List<Survey>> fetchAvailableSurveys();
 
-  /// Query the persisted event data stored on the user's machine
+  /// Query the persisted event data stored on the user's machine.
   ///
-  /// Returns null if there are no persisted logs
+  /// Returns null if there are no persisted logs.
   LogFileStats? logFileStats();
 
   /// Send preconfigured events using specific named constructors
-  /// on the [Event] class
+  /// on the [Event] class.
   ///
   /// Example
   /// ```dart
@@ -238,33 +244,37 @@ abstract class Analytics {
   Future<Response>? send(Event event);
 
   /// Pass a boolean to either enable or disable telemetry and make
-  /// the necessary changes in the persisted configuration file
+  /// the necessary changes in the persisted configuration file.
   ///
   /// Setting the telemetry status will also send an event to GA
-  /// indicating the latest status of the telemetry from [reportingBool]
+  /// indicating the latest status of the telemetry from [reportingBool].
   Future<void> setTelemetry(bool reportingBool);
 
   /// Calling this will result in telemetry collection being suppressed for
-  /// the current invocation
+  /// the current invocation.
   ///
   /// If you would like to permanently disable telemetry
-  /// collection use `setTelemetry(false)`
+  /// collection use:
+  ///
+  /// ```dart
+  /// analytics.setTelemetry(false)
+  /// ```
   void suppressTelemetry();
 
-  /// Method to run after interacting with a [Survey]
+  /// Method to run after interacting with a [Survey] instance.
   ///
   /// Pass a [Survey] instance which can be retrieved from
-  /// `fetchAvailableSurveys()`
+  /// [Analytics.fetchAvailableSurveys].
   ///
-  /// [surveyButton] is the button that was interacted with by the user
+  /// [surveyButton] is the button that was interacted with by the user.
   void surveyInteracted({
     required Survey survey,
     required SurveyButton surveyButton,
   });
 
-  /// Method to be called after a survey has been shown to the user
+  /// Method to be called after a survey has been shown to the user.
   ///
-  /// Calling this will snooze the survey so it won't be shown immediately
+  /// Calling this will snooze the survey so it won't be shown immediately.
   ///
   /// The snooze period is defined by the [Survey.snoozeForMinutes] field.
   void surveyShown(Survey survey);
@@ -286,27 +296,27 @@ class AnalyticsImpl implements Analytics {
   /// Tells the client if they need to show a message to the
   /// user; this will return true if it is the first time the
   /// package is being used for a developer or if the consent
-  /// message has been updated by the package
+  /// message has been updated by the package.
   late bool _showMessage;
 
   /// This will be switch to true once it has been confirmed by the
-  /// client using this package that they have shown this message
-  /// to the developer
+  /// client using this package that they have shown the
+  /// consent message to the developer.
   ///
   /// If the tool using this package as already shown the consent message
-  /// and it has been added to the config file, it will be set as true
+  /// and it has been added to the config file, it will be set as true.
   ///
   /// It will also be set to true once the tool using this package has
-  /// invoked [clientShowedMessage]
+  /// invoked [clientShowedMessage].
   ///
-  /// If this is false, all events will be blocked from being sent
+  /// If this is false, all events will be blocked from being sent.
   bool _clientShowedMessage = false;
 
   /// When set to `true`, various assert statements will be enabled
-  /// to ensure usage of this class is within GA4 limitations
+  /// to ensure usage of this class is within GA4 limitations.
   final bool _enableAsserts;
 
-  /// Telemetry suppression flag that is set via `suppressTelemetry()`
+  /// Telemetry suppression flag that is set via [Analytics.suppressTelemetry].
   bool _telemetrySuppressed = false;
 
   AnalyticsImpl({
@@ -399,18 +409,18 @@ class AnalyticsImpl implements Analytics {
   }
 
   /// Checking the [telemetryEnabled] boolean reflects what the
-  /// config file reflects
+  /// config file reflects.
   ///
   /// Checking the [_showMessage] boolean indicates if this the first
   /// time the tool is using analytics or if there has been an update
   /// the messaging found in constants.dart - in both cases, analytics
-  /// will not be sent until the second time the tool is used
+  /// will not be sent until the second time the tool is used.
   ///
-  /// Additionally, if the client has not invoked `clientShowedMessage`,
-  /// then no events shall be sent.
+  /// Additionally, if the client has not invoked
+  /// [Analytics.clientShowedMessage], then no events shall be sent.
   ///
   /// If the user has suppressed telemetry [_telemetrySuppressed] will
-  /// return `true` to prevent events from being sent for current invocation
+  /// return `true` to prevent events from being sent for current invocation.
   @override
   bool get okToSend =>
       telemetryEnabled &&

pkgs/unified_analytics/lib/src/asserts.dart

@@ -1,11 +1,15 @@
-/// Matches only alphabetic chars
+// Copyright (c) 2023, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// Matches only alphabetic characters.
 final RegExp alphabeticPattern = RegExp(r'^[A-Za-z]+$');
 
-/// Matches strings that contain alphanumeric chars and underscores
+/// Matches strings that contain alphanumeric characters and underscores.
 final RegExp alphaNumericPattern = RegExp(r'^[A-Za-z0-9_]+$');
 
 /// Checks that the body of the request being sent to
-/// GA4 is within the limitations
+/// GA4 is within the limitations.
 ///
 /// Limitations can be found:
 /// https://developers.google.com/analytics/devguides/collection/protocol/ga4/sending-events?client_type=gtag#limitations

pkgs/unified_analytics/lib/src/config_handler.dart

@@ -13,22 +13,22 @@ import 'constants.dart';
 import 'initializer.dart';
 import 'utils.dart';
 
-/// The regex pattern used to parse the disable analytics line
+/// The regex pattern used to parse the disable analytics line.
 const String telemetryFlagPattern = r'^reporting=([0|1]) *$';
 
 /// The regex pattern used to parse the tools info
-/// from the configuration file
+/// from the configuration file.
 ///
 /// Example:
+/// ```text
 /// flutter-tool=2022-10-26,1
+/// devtools=2022-11-26,1
+/// ```
 const String toolPattern =
     r'^([A-Za-z0-9]+[A-Za-z0-9_-]*)=([0-9]{4}-[0-9]{2}-[0-9]{2}),([0-9]+)$';
 
 class ConfigHandler {
-  /// Regex pattern implementation for matching a line in the config file
-  ///
-  /// Example:
-  /// flutter-tools=2022-10-26,1
+  /// Regex pattern implementation for matching a line in the config file.
   static RegExp telemetryFlagRegex =
       RegExp(telemetryFlagPattern, multiLine: true);
   static RegExp toolRegex = RegExp(toolPattern, multiLine: true);
@@ -63,11 +63,11 @@ class ConfigHandler {
     parseConfig();
   }
 
-  /// Returns the telemetry state from the config file
+  /// Returns the telemetry state from the config file.
   ///
   /// Method will reparse the config file if it detects that the
   /// last modified datetime is different from what was parsed when
-  /// the class was initialized
+  /// the class was initialized.
   bool get telemetryEnabled {
     if (configFileLastModified.isBefore(configFile.lastModifiedSync())) {
       parseConfig();
@@ -79,7 +79,7 @@ class ConfigHandler {
 
   /// Responsibe for the creation of the configuration line
   /// for the tool being passed in by the user and adding a
-  /// [ToolInfo] object
+  /// [ToolInfo] object.
   void addTool({
     required String tool,
     required int versionNumber,
@@ -103,7 +103,7 @@ class ConfigHandler {
 
   /// Will increment the version number and update the date
   /// in the config file for the provided tool name while
-  /// also incrementing the version number in [ToolInfo]
+  /// also incrementing the version number in [ToolInfo].
   void incrementToolVersion({
     required String tool,
     required int newVersionNumber,
@@ -146,7 +146,7 @@ class ConfigHandler {
   /// Method responsible for reading in the config file stored on
   /// user's machine and parsing out the following: all the tools that
   /// have been logged in the file, the dates they were last run, and
-  /// determining if telemetry is enabled by parsing the file
+  /// determining if telemetry is enabled by parsing the file.
   void parseConfig() {
     // Begin with the assumption that telemetry is always enabled
     _telemetryEnabled = true;
@@ -182,14 +182,14 @@ class ConfigHandler {
   }
 
   /// This will reset the configuration file and clear the
-  /// [parsedTools] map and trigger parsing the config again
+  /// [parsedTools] map and trigger parsing the config again.
   void resetConfig() {
     initializer.run(forceReset: true);
     parsedTools.clear();
     parseConfig();
   }
 
-  /// Disables the reporting capabilities if false is passed
+  /// Disables the reporting capabilities if [reportingBool] is set to `false`.
   Future<void> setTelemetry(bool reportingBool) async {
     final flag = reportingBool ? '1' : '0';
     final configString = await configFile.readAsString();