Improved PrettyPrinter documentation

Author: Bungeefan

lib/src/printers/pretty_printer.dart

@@ -44,50 +44,124 @@ class PrettyPrinter extends LogPrinter {
   };
 
   /// Matches a stacktrace line as generated on Android/iOS devices.
+  ///
   /// For example:
-  /// #1      Logger.log (package:logger/src/logger.dart:115:29)
+  /// * #1      Logger.log (package:logger/src/logger.dart:115:29)
   static final _deviceStackTraceRegex =
       RegExp(r'#[0-9]+[\s]+(.+) \(([^\s]+)\)');
 
   /// Matches a stacktrace line as generated by Flutter web.
+  ///
   /// For example:
-  /// packages/logger/src/printers/pretty_printer.dart 91:37
+  /// * packages/logger/src/printers/pretty_printer.dart 91:37
   static final _webStackTraceRegex =
       RegExp(r'^((packages|dart-sdk)\/[^\s]+\/)');
 
   /// Matches a stacktrace line as generated by browser Dart.
+  ///
   /// For example:
-  /// dart:sdk_internal
-  /// package:logger/src/logger.dart
+  /// * dart:sdk_internal
+  /// * package:logger/src/logger.dart
   static final _browserStackTraceRegex =
       RegExp(r'^(?:package:)?(dart:[^\s]+|[^\s]+)');
 
   static DateTime? _startTime;
 
-  /// The index which to begin the stack trace at
+  /// The index at which the stack trace should start.
   ///
   /// This can be useful if, for instance, Logger is wrapped in another class and
   /// you wish to remove these wrapped calls from stack trace
+  ///
+  /// See also:
+  /// * [excludePaths]
   final int stackTraceBeginIndex;
+
+  /// Controls the method count in created stack traces.
+  ///
+  /// This is used when no stack trace has been provided.
+  ///
+  /// Set to `0` to disable the creation of a stack trace.
+  ///
+  /// See also:
+  /// * [errorMethodCount]
   final int methodCount;
+
+  /// Controls the method count in provided stack traces.
+  ///
+  /// This is used when a stack trace was provided via the error parameter.
+  ///
+  /// Set to `0` in order to disable printing the provided stack trace.
+  ///
+  /// See also:
+  /// * [methodCount]
   final int errorMethodCount;
+
+  /// Controls the length of the divider lines.
   final int lineLength;
+
+  /// Whether ansi colors are used to color the output.
   final bool colors;
+
+  /// Whether emojis are prefixed to the log line.
   final bool printEmojis;
+
+  /// Whether [LogEvent.time] is printed.
   final bool printTime;
 
-  /// To prevent ascii 'boxing' of any log [Level] include the level in map for excludeBox,
-  /// for example to prevent boxing of [Level.verbose] and [Level.info] use excludeBox:{Level.verbose:true, Level.info:true}
+  /// Controls the ascii 'boxing' of different [Level]s.
+  ///
+  /// By default all levels are 'boxed',
+  /// to prevent 'boxing' of a specific level,
+  /// include it with `true` in the map.
+  ///
+  /// Example to prevent boxing of [Level.verbose] and [Level.info]:
+  /// ```dart
+  /// excludeBox: {
+  ///   Level.verbose: true,
+  ///   Level.info: true,
+  /// },
+  /// ```
+  ///
+  /// See also:
+  /// * [noBoxingByDefault]
   final Map<Level, bool> excludeBox;
 
-  /// To make the default for every level to prevent boxing entirely set [noBoxingByDefault] to true
-  /// (boxing can still be turned on for some levels by using something like excludeBox:{Level.error:false} )
+  /// Whether the implicit `bool`s in [excludeBox] are `true` or `false` by default.
+  ///
+  /// By default all levels are 'boxed',
+  /// this flips the default to no boxing for all levels.
+  /// Individual boxing can still be turned on for specific
+  /// levels by setting them manually to `false` in [excludeBox].
+  ///
+  /// Example to specifically activate 'boxing' of [Level.error]:
+  /// ```dart
+  /// noBoxingByDefault: true,
+  /// excludeBox: {
+  ///   Level.error: false,
+  /// },
+  /// ```
+  ///
+  /// See also:
+  /// * [excludeBox]
   final bool noBoxingByDefault;
 
-  /// To exclude user's custom path
-  /// for example if you made a Mylog util redirect to logger.log,
-  /// you can add your Mylog path in [excludePaths].
+  /// A list of custom paths that are excluded from the stack trace.
+  ///
+  /// For example, to exclude your `MyLog` util that redirects to this logger:
+  /// ```dart
+  /// excludePaths: [
+  ///   // To exclude a whole package
+  ///   "package:test",
+  ///   // To exclude a single file
+  ///   "package:test/util/my_log.dart",
+  /// ],
+  /// ```
+  ///
+  /// See also:
+  /// * [stackTraceBeginIndex]
   final List<String> excludePaths;
+
+  /// Contains the parsed rules resulting from [excludeBox] and [noBoxingByDefault].
   late final Map<Level, bool> includeBox;
 
   String _topBorder = '';