fix(config): Improved doc comments & value formatting of options (#82)

- fix(config): User friendly value formatting of Dir and File options
- docs(config): Fixed doc comment warnings

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Directory configuration now ensures directory paths include a trailing
separator for consistency.
* File configuration preserves file path formatting for reliable
handling.

* **Documentation**
* Escaped special characters in date-time configuration examples for
clearer documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: christerswahn

packages/config/lib/src/config/file_system_options.dart

@@ -1,6 +1,7 @@
 import 'dart:io';
 
 import 'package:args/command_runner.dart';
+import 'package:path/path.dart' as p;
 
 import 'options.dart';
 
@@ -17,6 +18,12 @@ class DirParser extends ValueParser<Directory> {
   Directory parse(final String value) {
     return Directory(value);
   }
+
+  @override
+  String format(final Directory value) {
+    final path = value.path;
+    return path.endsWith(p.separator) ? path : '$path${p.separator}';
+  }
 }
 
 /// Directory path configuration option.
@@ -81,6 +88,11 @@ class FileParser extends ValueParser<File> {
   File parse(final String value) {
     return File(value);
   }
+
+  @override
+  String format(final File value) {
+    return value.path;
+  }
 }
 
 /// File path configuration option.

packages/config/lib/src/config/option_types.dart

@@ -251,7 +251,7 @@ class IntOption extends ComparableValueOption<int> {
 ///
 /// This implementation is more forgiving than [DateTime.parse].
 /// In addition to the standard T and space separators between
-/// date and time it also allows [-_/:t].
+/// date and time it also allows \[-_/:t\].
 class DateTimeParser extends ValueParser<DateTime> {
   const DateTimeParser();
 

packages/config/lib/src/config/options.dart

@@ -3,7 +3,7 @@ import 'package:args/command_runner.dart';
 import 'package:collection/collection.dart';
 import 'package:meta/meta.dart';
 
-import 'configuration.dart';
+import 'configuration.dart' show Configuration;
 import 'configuration_broker.dart';
 import 'exceptions.dart';
 import 'option_resolution.dart';