Skip to content

Commit

Permalink
Clean up on dart docs across all dart files under lib (#142)
Browse files Browse the repository at this point in the history 
* Clean up across all dart files under lib

* Fix format

* Apply suggestions from code review

Co-authored-by: Christopher Fujino <fujino@google.com>

---------

Co-authored-by: Christopher Fujino <fujino@google.com>
  • Loading branch information
@eliasyishak @christopherfujino
eliasyishak and christopherfujino authored Aug 9, 2023
1 parent f14bf2e commit bc6c9f0
Show file tree
Hide file tree
Showing 13 changed files with 257 additions and 226 deletions.
102 changes: 56 additions & 46 deletions pkgs/unified_analytics/lib/src/analytics.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand All @@ -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);
Expand All @@ -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({
Expand Down Expand Up @@ -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 &&
Expand Down
10 changes: 7 additions & 3 deletions pkgs/unified_analytics/lib/src/asserts.dart
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down
26 changes: 13 additions & 13 deletions pkgs/unified_analytics/lib/src/config_handler.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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();
Expand All @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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();
Expand Down
Loading

0 comments on commit bc6c9f0

Please sign in to comment.