Add code documentation

packages/patrol_log/lib/patrol_log.dart

@@ -5,5 +5,6 @@ export 'src/entry.dart';
 export 'src/log_entry.dart';
 export 'src/patrol_log_reader.dart';
 export 'src/patrol_log_writer.dart';
+export 'src/patrol_single_test_entry.dart';
 export 'src/step_entry.dart';
 export 'src/test_entry.dart';

packages/patrol_log/lib/src/patrol_log_reader.dart

@@ -45,15 +45,26 @@ class PatrolLogReader {
   /// Stops the timer measuring whole tests duration.
   void stopTimer() => _stopwatch.stop();
 
+  /// Returns the total number of tests.
   int get totalTests => _singleEntries.length;
+
+  /// Returns the number of tests that passed.
   int get successfulTests =>
       _singleEntries.where((e) => e.status == TestEntryStatus.success).length;
-  Iterable<PatrolSingleTestEntry> get failedTests =>
-      _singleEntries.where((e) => e.status == TestEntryStatus.failure);
+
+  /// Return list of failed tests.
+  List<PatrolSingleTestEntry> get failedTests =>
+      _singleEntries.where((e) => e.status == TestEntryStatus.failure).toList();
+
+  /// Returns the number of failed tests.
   int get failedTestsCount => failedTests.length;
+
+  /// Returns the number of skipped tests.
   int get skippedTests =>
       _singleEntries.where((e) => e.status == TestEntryStatus.skip).length;
 
+  /// Returns `String` that have printed in bullet points name of failed tests
+  /// with relative path to file that contains the test.
   String get failedTestsList =>
       failedTests.map((e) => '  - ${e.nameWithPath}').join('\n');
 
@@ -97,6 +108,7 @@ class PatrolLogReader {
     return;
   }
 
+  /// Parses patrol log entry from JSON.
   static Entry parseEntry(String entryJson) {
     final json = jsonDecode(entryJson) as Map<String, dynamic>;
     final type = EntryType.values[json['type'] as int];
@@ -156,7 +168,15 @@ class PatrolLogReader {
     });
   }
 
-  /// Returns a summary of the test results.
+  /// Returns a summary of the test results. That contains:
+  ///
+  /// - Total number of tests
+  /// - Number of successful tests
+  /// - Number of failed tests
+  /// - List of failed tests
+  /// - Number of skipped tests
+  /// - Path to the report file
+  /// - Duration of the tests
   String get summary => 'Test summary:\n'
       '📝 Total: $totalTests\n'
       '✅ Successful: $successfulTests\n'
@@ -166,34 +186,22 @@ class PatrolLogReader {
       '📊 Report: $reportPath\n'
       '⏱️  Duration: ${_stopwatch.elapsed.inSeconds}s\n';
 
+  /// Closes the stream subscription and the stream controller.
   void close() {
     _streamSubscription.cancel();
     _controller.close();
   }
 
+  /// Clears `number` of lines from the console output.
   void _clearLines(int number) {
     for (var i = 0; i < number; i++) {
       _clearPreviousLine();
     }
   }
 
+  /// Clears the previous line from the console output.
   void _clearPreviousLine() {
     // Move the cursor up one line and clear the line
     stdout.write('\x1B[A\x1B[K');
   }
 }
-
-class PatrolSingleTestEntry {
-  PatrolSingleTestEntry(this.entries);
-
-  final List<Entry> entries;
-
-  String get name =>
-      (entries.firstWhere((t) => t is TestEntry) as TestEntry).name;
-
-  TestEntryStatus get status =>
-      (entries.lastWhere((t) => t is TestEntry) as TestEntry).status;
-
-  String get nameWithPath =>
-      (entries.lastWhere((t) => t is TestEntry) as TestEntry).nameWithPath;
-}

packages/patrol_log/lib/src/patrol_log_writer.dart

@@ -19,7 +19,7 @@ class PatrolLogWriter {
   /// Writes the entries to the console.
   void write() {
     _streamSubscription = _controller.stream.listen((entry) {
-      // Print to standard output
+      // Print to standard output, so it can be read by the CLI.
       // ignore: avoid_print
       print('PATROL_LOG ${jsonEncode(entry.toJson())}');
     });

packages/patrol_log/lib/src/patrol_single_test_entry.dart

@@ -0,0 +1,28 @@
+import 'package:patrol_log/patrol_log.dart';
+
+/// Represents a single test entry.
+///
+/// A single test entry is a collection of entries that belong to the same test.
+/// It starts with a [TestEntry] with status [TestEntryStatus.start] or
+/// [TestEntryStatus.skip].
+/// Entry with skip status contains only one entry.
+/// Entry with start status contains also [StepEntry] and [LogEntry] entries.
+/// The last entry in the collection is a test entry with status
+/// [TestEntryStatus.success] or [TestEntryStatus.failure].
+class PatrolSingleTestEntry {
+  PatrolSingleTestEntry(this.entries);
+
+  final List<Entry> entries;
+
+  /// The name of the test.
+  String get name =>
+      (entries.firstWhere((t) => t is TestEntry) as TestEntry).name;
+
+  /// The status of the test.
+  TestEntryStatus get status =>
+      (entries.lastWhere((t) => t is TestEntry) as TestEntry).status;
+
+  /// The name of the test with the path.
+  String get nameWithPath =>
+      (entries.lastWhere((t) => t is TestEntry) as TestEntry).nameWithPath;
+}