docs: improve api documentation

lib/src/stash.dart

@@ -2,20 +2,21 @@ import 'package:libgit2dart/libgit2dart.dart';
 import 'bindings/stash.dart' as bindings;
 
 class Stash {
-  /// Initializes a new instance of [Stash] class.
+  /// Initializes a new instance of [Stash] class from provided stash [index], [message]
+  /// and [oid].
   const Stash({
     required this.index,
     required this.message,
     required this.oid,
   });
 
-  /// The position within the stash list.
+  /// Position within the stash list.
   final int index;
 
-  /// The stash message.
+  /// Stash message.
   final String message;
 
-  /// The commit oid of the stashed state.
+  /// Commit [Oid] of the stashed state.
   final Oid oid;
 
   /// Returns list of all the stashed states, first being the most recent.
@@ -23,30 +24,47 @@ class Stash {
 
   /// Saves the local modifications to a new stash.
   ///
+  /// [repo] is the owning repository.
+  ///
+  /// [stasher] is the identity of the person performing the stashing.
+  ///
+  /// [message] is optional description along with the stashed state.
+  ///
+  /// [flags] is a combination of [GitStash] flags. Defaults to [GitStash.defaults].
+  ///
   /// Throws a [LibGit2Error] if error occured.
   static Oid create({
     required Repository repo,
     required Signature stasher,
     String? message,
-    bool keepIndex = false,
-    bool includeUntracked = false,
-    bool includeIgnored = false,
+    Set<GitStash> flags = const {GitStash.defaults},
   }) {
-    int flags = 0;
-    if (keepIndex) flags |= GitStash.keepIndex.value;
-    if (includeUntracked) flags |= GitStash.includeUntracked.value;
-    if (includeIgnored) flags |= GitStash.includeIgnored.value;
+    final int flagsInt = flags.fold(0, (acc, e) => acc | e.value);
 
     return Oid(bindings.save(
       repoPointer: repo.pointer,
       stasherPointer: stasher.pointer,
       message: message,
-      flags: flags,
+      flags: flagsInt,
     ));
   }
 
   /// Applies a single stashed state from the stash list.
   ///
+  /// [index] is the position of the stashed state in the list. Defaults to last saved.
+  ///
+  /// [reinstateIndex] whether to try to reinstate not only the working tree's changes,
+  /// but also the index's changes.
+  ///
+  /// [strategy] is a combination of [GitCheckout] flags. Defaults to [GitCheckout.safe]
+  /// with [GitCheckout.recreateMissing].
+  ///
+  /// [directory] is the alternative checkout path to workdir, can be null.
+  ///
+  /// [paths] is a list of wildmatch patterns or paths. By default, all paths are processed.
+  /// If you pass a list of wildmatch patterns, those will be used to filter which paths
+  /// should be taken into account.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   static void apply({
     required Repository repo,
@@ -69,7 +87,8 @@ class Stash {
     );
   }
 
-  /// Removes a single stashed state from the stash list.
+  /// Removes a single stashed state from the stash list at provided [index]. Defaults to
+  /// the last saved stash.
   ///
   /// Throws a [LibGit2Error] if error occured.
   static void drop({required Repository repo, int index = 0}) {
@@ -82,6 +101,20 @@ class Stash {
   /// Applies a single stashed state from the stash list and remove it from
   /// the list if successful.
   ///
+  /// [index] is the position of the stashed state in the list. Defaults to last saved.
+  ///
+  /// [reinstateIndex] whether to try to reinstate not only the working tree's changes,
+  /// but also the index's changes.
+  ///
+  /// [strategy] is a combination of [GitCheckout] flags. Defaults to [GitCheckout.safe]
+  /// with [GitCheckout.recreateMissing].
+  ///
+  /// [directory] is the alternative checkout path to workdir, can be null.
+  ///
+  /// [paths] is a list of wildmatch patterns or paths. By default, all paths are processed.
+  /// If you pass a list of wildmatch patterns, those will be used to filter which paths
+  /// should be taken into account.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   static void pop({
     required Repository repo,