Add more documentation

Author: passsy

lib/src/pick_bool.dart

@@ -12,6 +12,8 @@ extension BoolPick on RequiredPick {
 }
 
 extension NullableBoolPick on Pick {
+  // This deprecation is used to promote the `.required()` in auto-completion.
+  // Therefore it is not intended to be ever removed
   @Deprecated(
       'By default values are optional and can only be converted when a fallback is provided '
       'i.e. .asBoolOrNull() which falls back to `null`. '

lib/src/pick_datetime.dart

@@ -30,6 +30,8 @@ extension DateTimePick on RequiredPick {
 }
 
 extension NullableDateTimePick on Pick {
+  // This deprecation is used to promote the `.required()` in auto-completion.
+  // Therefore it is not intended to be ever removed
   @Deprecated(
       'By default values are optional and can only be converted when a fallback is provided '
       'i.e. .asDateTimeOrNull() which falls back to `null`. '

lib/src/pick_double.dart

@@ -18,6 +18,8 @@ extension DoublePick on RequiredPick {
 }
 
 extension NullableDoublePick on Pick {
+  // This deprecation is used to promote the `.required()` in auto-completion.
+  // Therefore it is not intended to be ever removed
   @Deprecated(
       'By default values are optional and can only be converted when a fallback is provided '
       'i.e. .asDoubleOrNull() which falls back to `null`. '

lib/src/pick_int.dart

@@ -1,6 +1,13 @@
 import 'package:deep_pick/src/pick.dart';
 
 extension IntPick on RequiredPick {
+  /// Returns the picked [value] as [int]
+  ///
+  /// {@template Pick.asInt}
+  /// Parses the picked value as [int]. Other types are parsable as well
+  /// - [String] is gets parsed via [int.tryParse]
+  /// - [double] is gets converted to [int] via [num.toInt()]
+  /// {@endtemplate}
   int asInt() {
     if (value is int) {
       return value as int;
@@ -18,6 +25,8 @@ extension IntPick on RequiredPick {
 }
 
 extension NullableIntPick on Pick {
+  // This deprecation is used to promote the `.required()` in auto-completion.
+  // Therefore it is not intended to be ever removed
   @Deprecated(
       'By default values are optional and can only be converted when a fallback is provided '
       'i.e. .asIntOrNUll() which falls back to `null`. '
@@ -31,6 +40,10 @@ extension NullableIntPick on Pick {
     return required().asInt();
   }
 
+  /// Returns the picked [value] as [int?] or returns `null` when the picked
+  /// value is absent
+  ///
+  /// {@macro Pick.asInt}
   int? asIntOrNull() {
     if (value == null) return null;
     try {

lib/src/pick_list.dart

@@ -19,6 +19,8 @@ extension ListPick on RequiredPick {
 }
 
 extension NullableListPick on Pick {
+  // This deprecation is used to promote the `.required()` in auto-completion.
+  // Therefore it is not intended to be ever removed
   @Deprecated(
       'By default values are optional and can only be converted when a fallback is provided '
       'i.e. .asListOrNull() which falls back to `null`. '

lib/src/pick_map.dart

@@ -15,6 +15,8 @@ extension MapPick on RequiredPick {
 }
 
 extension NullableMapPick on Pick {
+  // This deprecation is used to promote the `.required()` in auto-completion.
+  // Therefore it is not intended to be ever removed
   @Deprecated(
       'By default values are optional and can only be converted when a fallback is provided '
       'i.e. .asMapOrNull() which falls back to `null`. '

lib/src/pick_string.dart

@@ -1,6 +1,14 @@
 import 'package:deep_pick/src/pick.dart';
 
 extension StringPick on RequiredPick {
+  /// Returns the picked [value] as String
+  ///
+  /// {@template Pick.asString}
+  /// Parses the picked value as String. If the value is not already a [String]
+  /// its [Object.toString()] will be called. This means that this method works
+  /// for [int], [double] and any other [Object] which isn't a collection of
+  /// values such as a [List] or [Map]
+  /// {@endtemplate}
   String asString() {
     if (value is String) {
       return value as String;
@@ -17,19 +25,23 @@ extension StringPick on RequiredPick {
 }
 
 extension NullableStringPick on Pick {
+  // This deprecation is used to promote the `.required()` in auto-completion.
+  // Therefore it is not intended to be ever removed
   @Deprecated(
-      'By default values are optional and can only be converted when a fallback is provided '
-      'i.e. .asStringOrNull() which falls back to `null`. '
-      'Use .required().asString() in cases the value is mandatory. '
-      "It will crash when the value couldn't be picked.")
+      'Use .required().asString() or .asRequiredString() when you require the value to be non-null. '
+      'Use .asStringOrNull() when you expect the value to be nullable')
   String asString() {
     if (value == null) {
       throw PickException(
-          'value at location ${location()} is null and not an instance of String');
+          'value at location ${location()} is null and not a String. '
+          'Use asStringOrNull() when null is a valid value (String?)');
     }
     return required().asString();
   }
 
+  /// Returns the picked [value] as [String] or returns `null` when the picked value isn't available
+  ///
+  /// {@macro Pick.asString}
   String? asStringOrNull() {
     if (value == null) return null;
     try {

test/src/required_pick_test.dart

@@ -30,8 +30,10 @@ void main() {
       expect(picked('adam').asString(), 'adam');
       expect(picked(1).asString(), '1');
       expect(picked(2.0).asString(), '2.0');
-      expect(() => nullPick().asString(),
-          throwsA(pickException(containing: ['unknownKey', 'null', 'String'])));
+      expect(
+          () => nullPick().asString(),
+          throwsA(pickException(
+              containing: ['unknownKey', 'null', 'String', 'asStringOrNull'])));
     });
 
     test("asString() doesn't transform Maps and Lists with toString", () {