Analysis: update docs (#41)

generator/lib/src/analysis/analysis.dart

@@ -54,7 +54,8 @@ class ObjectBoxAnalysis {
     }
   }
 
-  /// Sends an event String that represents a JSON object.
+  /// Sends an [Event] and returns the response. May return null if the API
+  /// token could not be obtained.
   Future<http.Response?> sendEvent(Event event) async {
     final token = await _getToken();
     if (token == null || token.isEmpty) {
@@ -72,7 +73,7 @@ class ObjectBoxAnalysis {
         body: body);
   }
 
-  /// Returns the event as a string representation of a JSON object.
+  /// Uses the given values to gather properties and return them as an [Event].
   Event buildEvent(String eventName, String distinctId, Pubspec? pubspec) {
     final properties = <String, String>{};
     properties["distinct_id"] = distinctId;
@@ -133,6 +134,8 @@ class ObjectBoxAnalysis {
     return null;
   }
 
+  /// Takes a Base64 encoded secret key and secret text (which is a [SecretBox]
+  /// concatenation) and returns the decrypted text.
   Future<String> decryptToken(
       String secretKeyBase64, String secretTextBase64) async {
     final algorithm = Chacha20.poly1305Aead();
@@ -150,13 +153,16 @@ class ObjectBoxAnalysis {
   }
 }
 
-/// Wrapper for data to be sent for analysis.
+/// Wrapper for data to be sent for analysis. Use [toJson] to return a
+/// JSON object representation.
 class Event {
   final String name;
   final Map<String, String> properties;
 
+  /// See class documentation.
   Event(this.name, this.properties);
 
+  /// Return this as a JSON object.
   String toJson() {
     final map = {'event': name, 'properties': properties};
     return jsonEncode(map);

generator/lib/src/analysis/build_properties.dart

@@ -74,8 +74,8 @@ class BuildProperties {
 
   /// Writes the current values to a file. Returns if it was successful.
   ///
-  /// By default uses a file in the users home directory using the default
-  /// file name. Supply [filePath] to use that instead.
+  /// By default uses a file in the [getOutDirectoryPath] using the default
+  /// [_fileName]. Supply [filePath] to use that instead.
   Future<bool> write({String? filePath}) async {
     final file = _buildFile(filePath);
     if (file == null) {
@@ -91,7 +91,7 @@ class BuildProperties {
     }
   }
 
-  /// Creates a file using the default file name in the [getOutDirectoryPath].
+  /// Creates a file using the default [_fileName] in the [getOutDirectoryPath].
   /// Supply [filePath] to use that instead.
   static File? _buildFile(String? filePath) {
     if (filePath == null) {
@@ -136,7 +136,7 @@ class BuildProperties {
     final uidBytes = Uint8List(8)..buffer.asInt64List()[0] = uid;
     var uidEncoded = base64Encode(uidBytes);
 
-    // Remove the padding as the values is never decoded.
+    // Remove the padding as the value is never decoded.
     while (uidEncoded.endsWith("=")) {
       uidEncoded = uidEncoded.substring(0, uidEncoded.length - 1);
     }