docs: improve api documentation

lib/src/blame.dart

@@ -6,10 +6,13 @@ import 'bindings/libgit2_bindings.dart';
 import 'bindings/blame.dart' as bindings;
 
 class Blame with IterableMixin<BlameHunk> {
-  /// Initializes a new instance of the [Blame] class by getting
+  /// Returns the blame for a single file.
-  /// the blame for a single file.
   ///
-  /// [flags] is a combination of [GitBlameFlag]s.
+  /// [repo] is the repository whose history is to be walked.
+  ///
+  /// [path] is the path to file to consider.
+  ///
+  /// [flags] is a combination of [GitBlameFlag]s. Defaults to [GitBlameFlag.normal].
   ///
   /// [minMatchCharacters] is the lower bound on the number of alphanumeric
   /// characters that must be detected as moving/copying within a file for
@@ -28,6 +31,8 @@ class Blame with IterableMixin<BlameHunk> {
   /// [maxLine] is the last line in the file to blame. The default is the last
   /// line of the file.
   ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   Blame.file({
     required Repository repo,
@@ -64,7 +69,7 @@ class Blame with IterableMixin<BlameHunk> {
     ));
   }
 
-  /// Gets the hunk that relates to the given line number (1-based) in the newest commit.
+  /// Returns the hunk that relates to the given line number (1-based) in the newest commit.
   ///
   /// Throws [RangeError] if [lineNumber] is out of range.
   BlameHunk forLine(int lineNumber) {
@@ -89,43 +94,42 @@ class BlameHunk {
   /// Pointer to memory address for allocated blame hunk object.
   final Pointer<git_blame_hunk> _blameHunkPointer;
 
-  /// Returns the number of lines in this hunk.
+  /// Number of lines in this hunk.
   int get linesCount => _blameHunkPointer.ref.lines_in_hunk;
 
-  /// Checks if the hunk has been tracked to a boundary commit
+  /// Whether the hunk has been tracked to a boundary commit
-  /// (the root, or the commit specified in [oldestCommit] argument)
+  /// (the root, or the commit specified in [oldestCommit] argument).
   bool get isBoundary {
     return _blameHunkPointer.ref.boundary == 1 ? true : false;
   }
 
-  /// Returns the 1-based line number where this hunk begins, in the final
+  /// 1-based line number where this hunk begins, in the final version of the file.
-  /// version of the file.
   int get finalStartLineNumber => _blameHunkPointer.ref.final_start_line_number;
 
-  /// Returns the author of [finalCommitOid]. If [GitBlameFlag.useMailmap] has been
+  /// Author of [finalCommitOid]. If [GitBlameFlag.useMailmap] has been
   /// specified, it will contain the canonical real name and email address.
   Signature get finalCommitter =>
       Signature(_blameHunkPointer.ref.final_signature);
 
-  /// Returns the [Oid] of the commit where this line was last changed.
+  /// [Oid] of the commit where this line was last changed.
   Oid get finalCommitOid => Oid.fromRaw(_blameHunkPointer.ref.final_commit_id);
 
-  /// Returns the 1-based line number where this hunk begins, in the file
+  /// 1-based line number where this hunk begins, in the file named by [originPath]
-  /// named by [originPath] in the commit specified by [originCommitId].
+  /// in the commit specified by [originCommitId].
   int get originStartLineNumber => _blameHunkPointer.ref.orig_start_line_number;
 
-  /// Returns the author of [originCommitOid]. If [GitBlameFlag.useMailmap] has been
+  /// Author of [originCommitOid]. If [GitBlameFlag.useMailmap] has been
   /// specified, it will contain the canonical real name and email address.
   Signature get originCommitter =>
       Signature(_blameHunkPointer.ref.orig_signature);
 
-  /// Returns the [Oid] of the commit where this hunk was found. This will usually be
+  /// [Oid] of the commit where this hunk was found. This will usually be the same
-  /// the same as [finalCommitOid], except when [GitBlameFlag.trackCopiesAnyCommitCopies]
+  /// as [finalCommitOid], except when [GitBlameFlag.trackCopiesAnyCommitCopies]
   /// been specified.
   Oid get originCommitOid => Oid.fromRaw(_blameHunkPointer.ref.orig_commit_id);
 
-  /// Returns the path to the file where this hunk originated, as of the commit
+  /// Path to the file where this hunk originated, as of the commit specified by
-  /// specified by [originCommitOid].
+  /// [originCommitOid].
   String get originPath =>
       _blameHunkPointer.ref.orig_path.cast<Utf8>().toDartString();
 

lib/src/blob.dart

@@ -8,12 +8,12 @@ class Blob {
   /// Initializes a new instance of [Blob] class from provided pointer to
   /// blob object in memory.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Blob(this._blobPointer);
 
   /// Lookups a blob object for provided [oid] in a [repo]sitory.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Blob.lookup({required Repository repo, required Oid oid}) {
     _blobPointer = bindings.lookup(
       repoPointer: repo.pointer,
@@ -58,25 +58,39 @@ class Blob {
     return Oid(bindings.createFromDisk(repoPointer: repo.pointer, path: path));
   }
 
-  /// Returns the [Oid] of the blob.
+  /// [Oid] of the blob.
   Oid get oid => Oid(bindings.id(_blobPointer));
 
-  /// Determines if the blob content is most certainly binary or not.
+  /// Whether the blob content is most certainly binary or not.
   ///
   /// The heuristic used to guess if a file is binary is taken from core git:
   /// Searching for NUL bytes and looking for a reasonable ratio of printable to
   /// non-printable characters among the first 8000 bytes.
   bool get isBinary => bindings.isBinary(_blobPointer);
 
-  /// Returns a read-only buffer with the raw content of a blob.
+  /// Read-only buffer with the raw content of a blob.
   String get content => bindings.content(_blobPointer);
 
-  /// Returns the size in bytes of the contents of a blob.
+  /// Size in bytes of the contents of a blob.
   int get size => bindings.size(_blobPointer);
 
-  /// Directly generate a [Patch] from the difference between two blobs.
+  /// Directly generates a [Patch] from the difference between two blobs.
   ///
-  /// Should be freed with `free()` to release allocated memory.
+  /// [newBlob] is the blob for new side of diff, or null for empty blob.
+  ///
+  /// [oldAsPath] treat old blob as if it had this filename, can be null.
+  ///
+  /// [newAsPath] treat new blob as if it had this filename, can be null.
+  ///
+  /// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
+  ///
+  /// [contextLines] is the number of unchanged lines that define the boundary
+  /// of a hunk (and to display before and after). Defaults to 3.
+  ///
+  /// [interhunkLines] is the maximum number of unchanged lines between hunk
+  /// boundaries before the hunks will be merged into one. Defaults to 0.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Patch diff({
@@ -104,9 +118,23 @@ class Blob {
     );
   }
 
-  /// Directly generate a [Patch] from the difference between the blob and a buffer.
+  /// Directly generates a [Patch] from the difference between the blob and a buffer.
   ///
-  /// Should be freed with `free()` to release allocated memory.
+  /// [buffer] is the raw data for new side of diff, or null for empty.
+  ///
+  /// [oldAsPath] treat old blob as if it had this filename, can be null.
+  ///
+  /// [bufferAsPath] treat buffer as if it had this filename, can be null.
+  ///
+  /// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
+  ///
+  /// [contextLines] is the number of unchanged lines that define the boundary
+  /// of a hunk (and to display before and after). Defaults to 3.
+  ///
+  /// [interhunkLines] is the maximum number of unchanged lines between hunk
+  /// boundaries before the hunks will be merged into one. Defaults to 0.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Patch diffToBuffer({

lib/src/branch.dart

@@ -8,19 +8,22 @@ class Branch {
   /// Initializes a new instance of [Branch] class from provided pointer to
   /// branch object in memory.
   ///
-  /// Should be freed with [free] to release allocated memory when no longer
+  /// **IMPORTANT**: Should be freed to release allocated memory.
-  /// needed.
   Branch(this._branchPointer);
 
   /// Creates a new branch pointing at a [target] commit.
   ///
   /// A new direct reference will be created pointing to this target commit.
-  /// If [force] is true and a reference already exists with the given name, it'll be replaced.
+  /// If [force] is true and a reference already exists with the given name,
+  /// it'll be replaced.
   ///
-  /// Should be freed with [free] to release allocated memory when no longer
+  /// [name] is the name for the branch, this name is validated for consistency.
-  /// needed.
+  /// It should also not conflict with an already existing branch name.
   ///
-  /// The branch name will be checked for validity.
+  /// [target] is the commit to which this branch should point. This object must
+  /// belong to the given [repo].
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Branch.create({
@@ -44,7 +47,7 @@ class Branch {
   /// If branch [type] is [GitBranch.remote] you must include the remote name
   /// in the [name] (e.g. "origin/master").
   ///
-  /// Should be freed to release allocated memory when no longer needed.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Branch.lookup({
@@ -67,7 +70,7 @@ class Branch {
   /// Returns a list of branches that can be found in a [repo]sitory for provided [type].
   /// Default is all branches (local and remote).
   ///
-  /// IMPORTANT: Branches must be freed manually when no longer needed to prevent
+  /// **IMPORTANT**: Branches must be freed manually when no longer needed to prevent
   /// memory leak.
   ///
   /// Throws a [LibGit2Error] if error occured.
@@ -83,7 +86,7 @@ class Branch {
     return pointers.map((e) => Branch(e)).toList();
   }
 
-  /// Deletes an existing branch reference.
+  /// Deletes an existing branch reference with provided [name].
   ///
   /// Throws a [LibGit2Error] if error occured.
   static void delete({required Repository repo, required String name}) {
@@ -92,9 +95,9 @@ class Branch {
     branch.free();
   }
 
-  /// Renames an existing local branch reference.
+  /// Renames an existing local branch reference with provided [oldName].
   ///
-  /// The new branch name will be checked for validity.
+  /// The new branch name [newName] will be checked for validity.
   ///
   /// If [force] is true, existing branch will be overwritten.
   ///
@@ -116,17 +119,17 @@ class Branch {
     branch.free();
   }
 
-  /// Returns the [Oid] pointed to by a branch.
+  /// [Oid] pointed to by a branch.
   ///
-  /// Throws an exception if error occured.
+  /// Throws an [Exception] if error occured.
   Oid get target => Oid(reference_bindings.target(_branchPointer));
 
-  /// Checks if HEAD points to the given branch.
+  /// Whether HEAD points to the given branch.
   ///
   /// Throws a [LibGit2Error] if error occured.
   bool get isHead => bindings.isHead(_branchPointer);
 
-  /// Checks if any HEAD points to the current branch.
+  /// Whether any HEAD points to the current branch.
   ///
   /// This will iterate over all known linked repositories (usually in the form of worktrees)
   /// and report whether any HEAD is pointing at the current branch.
@@ -134,10 +137,10 @@ class Branch {
   /// Throws a [LibGit2Error] if error occured.
   bool get isCheckedOut => bindings.isCheckedOut(_branchPointer);
 
-  /// Returns the branch name.
+  /// Branch name.
   ///
   /// Given a reference object, this will check that it really is a branch
-  /// (ie. it lives under "refs/heads/" or "refs/remotes/"), and return the branch part of it.
+  /// (i.e. it lives under "refs/heads/" or "refs/remotes/"), and return the branch part of it.
   ///
   /// Throws a [LibGit2Error] if error occured.
   String get name => bindings.name(_branchPointer);

lib/src/callbacks.dart

@@ -1,6 +1,20 @@
 import 'package:libgit2dart/libgit2dart.dart';
 
 class Callbacks {
+  /// Callback functions used in various methods of [Remote] and with [Repository.clone].
+  ///
+  /// [credentials] is the [Credentials] object used for authentication.
+  ///
+  /// [transferProgress] is the callback function that reports transfer progress.
+  ///
+  /// [sidebandProgress] is the callback function that reports textual progress from the remote.
+  ///
+  /// [updateTips] is the callback function matching the
+  /// `void Function(String refname, Oid old, Oid new)` that report reference updates.
+  ///
+  /// [pushUpdateReference] is the callback function matching the
+  /// `void Function(String refname, String message)` used to inform of the update status
+  /// from the remote.
   const Callbacks({
     this.credentials,
     this.transferProgress,

lib/src/commit.dart

@@ -8,12 +8,12 @@ class Commit {
   /// Initializes a new instance of [Commit] class from provided pointer to
   /// commit object in memory.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Commit(this._commitPointer);
 
-  /// Lookups commit object for provided [oid] in a [repo]sitory.
+  /// Lookups commit object for provided [oid] in the [repo]sitory.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Commit.lookup({required Repository repo, required Oid oid}) {
     _commitPointer = bindings.lookup(
       repoPointer: repo.pointer,
@@ -26,30 +26,49 @@ class Commit {
   /// Pointer to memory address for allocated commit object.
   Pointer<git_commit> get pointer => _commitPointer;
 
-  /// Creates new commit in the repository.
+  /// Creates new commit in the [repo]sitory.
   ///
-  /// [updateRef] is name of the reference that will be updated to point to this commit.
+  /// [repo] is the repository where to store the commit.
+  ///
+  /// [updateRef] is the name of the reference that will be updated to point to this commit.
   /// If the reference is not direct, it will be resolved to a direct reference. Use "HEAD"
   /// to update the HEAD of the current branch and make it point to this commit. If the
   /// reference doesn't exist yet, it will be created. If it does exist, the first parent
   /// must be the tip of this branch.
   ///
+  /// [author] is the signature with author and author time of commit.
+  ///
+  /// [committer] is the signature with committer and commit time of commit.
+  ///
+  /// [messageEncoding] is the encoding for the message in the commit, represented with
+  /// a standard encoding name. E.g. "UTF-8". If null, no encoding header is written and
+  /// UTF-8 is assumed.
+  ///
+  /// [message] is the full message for this commit.
+  ///
+  /// [tree] is an instance of a [Tree] object that will be used as the tree for the commit.
+  /// This tree object must also be owned by the given [repo].
+  ///
+  /// [parents] is a list of [Commit] objects that will be used as the parents for this commit.
+  /// This array may be empty if parent count is 0 (root commit). All the given commits must
+  /// be owned by the [repo].
+  ///
   /// Throws a [LibGit2Error] if error occured.
   static Oid create({
     required Repository repo,
-    required String message,
+    String? updateRef,
     required Signature author,
-    required Signature commiter,
+    required Signature committer,
+    String? messageEncoding,
+    required String message,
     required Tree tree,
     required List<Commit> parents,
-    String? updateRef,
-    String? messageEncoding,
   }) {
     return Oid(bindings.create(
       repoPointer: repo.pointer,
       updateRef: updateRef,
       authorPointer: author.pointer,
-      committerPointer: commiter.pointer,
+      committerPointer: committer.pointer,
       messageEncoding: messageEncoding,
       message: message,
       treePointer: tree.pointer,
@@ -68,6 +87,12 @@ class Commit {
   /// the tip of the branch and then rewrite the following commits to reach a ref, pass
   /// this as null and update the rest of the commit chain and ref separately.
   ///
+  /// Unlike [create], the [author], [committer], [message], [messageEncoding], and
+  /// [tree] arguments can be null in which case this will use the values from the original
+  /// [commit].
+  ///
+  /// All arguments have the same meanings as in [create].
+  ///
   /// Throws a [LibGit2Error] if error occured.
   static Oid amend({
     required Repository repo,
@@ -91,28 +116,29 @@ class Commit {
     ));
   }
 
-  /// Returns the encoding for the message of a commit, as a string
+  /// Wncoding for the message of a commit, as a string representing a standard
-  /// representing a standard encoding name.
+  /// encoding name.
   String get messageEncoding => bindings.messageEncoding(_commitPointer);
 
-  /// Returns the full message of a commit.
+  /// Full message of a commit.
   ///
-  /// The returned message will be slightly prettified by removing any potential leading newlines.
+  /// The returned message will be slightly prettified by removing any potential
+  /// leading newlines.
   String get message => bindings.message(_commitPointer);
 
-  /// Returns the [Oid] of a commit.
+  /// [Oid] of a commit.
   Oid get oid => Oid(bindings.id(_commitPointer));
 
-  /// Returns the commit time (i.e. committer time) of a commit.
+  /// Commit time (i.e. committer time) of a commit.
   int get time => bindings.time(_commitPointer);
 
-  /// Returns the committer of a commit.
+  /// Committer of a commit.
   Signature get committer => Signature(bindings.committer(_commitPointer));
 
-  /// Returns the author of a commit.
+  /// Author of a commit.
   Signature get author => Signature(bindings.author(_commitPointer));
 
-  /// Returns list of parent commits [Oid]s.
+  /// List of parent commits [Oid]s.
   List<Oid> get parents {
     var parents = <Oid>[];
     final parentCount = bindings.parentCount(_commitPointer);
@@ -128,7 +154,7 @@ class Commit {
     return parents;
   }
 
-  /// Get the tree pointed to by a commit.
+  /// Tree pointed to by a commit.
   Tree get tree {
     return Tree(tree_bindings.lookup(
       repoPointer: bindings.owner(_commitPointer),
@@ -152,8 +178,9 @@ class Commit {
 ///
 /// Note: for internal use.
 class AnnotatedCommit {
-  /// Lookups an annotated commit from the given commit [oid]. The resulting annotated commit
+  /// Lookups an annotated commit from the given commit [oid].
-  /// must be freed to release allocated memory.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   AnnotatedCommit.lookup({required Repository repo, required Oid oid}) {

lib/src/config.dart

@@ -11,17 +11,17 @@ class Config with IterableMixin<ConfigEntry> {
   /// Initializes a new instance of [Config] class from provided
   /// pointer to config object in memory.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Config(this._configPointer);
 
-  /// Initializes a new instance of [Config] class from provided [path].
+  /// Opens config file at provided [path].
   ///
   /// If [path] isn't provided, opens global, XDG and system config files.
   ///
   /// [path] should point to single on-disk file; it's expected to be a native
   /// Git config file following the default Git config syntax (see man git-config).
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws an [Exception] if file not found at provided path.
   Config.open([String? path]) {
@@ -38,11 +38,9 @@ class Config with IterableMixin<ConfigEntry> {
     }
   }
 
-  /// Initializes a new instance of [Config] class.
-  ///
   /// Opens the system configuration file.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Config.system() {
@@ -51,11 +49,9 @@ class Config with IterableMixin<ConfigEntry> {
     _configPointer = bindings.open(bindings.findSystem());
   }
 
-  /// Initializes a new instance of [Config] class.
-  ///
   /// Opens the global configuration file.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Config.global() {
@@ -64,11 +60,9 @@ class Config with IterableMixin<ConfigEntry> {
     _configPointer = bindings.open(bindings.findGlobal());
   }
 
-  /// Initializes a new instance of [Config] class.
-  ///
   /// Opens the global XDG configuration file.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Config.xdg() {
@@ -80,9 +74,7 @@ class Config with IterableMixin<ConfigEntry> {
   /// Pointer to memory address for allocated config object.
   late final Pointer<git_config> _configPointer;
 
-  /// Create a snapshot of the configuration.
+  /// The snapshot of the current state of a configuration, which allows you to look
-  ///
-  /// Create a snapshot of the current state of a configuration, which allows you to look
   /// into a consistent view of the configuration for looking up complex values
   /// (e.g. a remote, submodule).
   Config get snapshot => Config(bindings.snapshot(_configPointer));
@@ -181,21 +173,25 @@ class Config with IterableMixin<ConfigEntry> {
 }
 
 class ConfigEntry {
+  /// Initializes a new instance of [ConfigEntry] class from provided
+  /// pointer to config entry object in memory.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   const ConfigEntry(this._configEntryPointer);
 
   /// Pointer to memory address for allocated config entry object.
   final Pointer<git_config_entry> _configEntryPointer;
 
-  /// Returns name of the entry (normalised).
+  /// Name of the entry (normalised).
   String get name => _configEntryPointer.ref.name.cast<Utf8>().toDartString();
 
-  /// Returns value of the entry.
+  /// Value of the entry.
   String get value => _configEntryPointer.ref.value.cast<Utf8>().toDartString();
 
-  /// Returns depth of includes where this variable was found
+  /// Depth of includes where this variable was found
   int get includeDepth => _configEntryPointer.ref.include_depth;
 
-  /// Returns which config file this was found in.
+  /// Which config file this was found in.
   GitConfigLevel get level {
     return GitConfigLevel.values.singleWhere(
       (e) => _configEntryPointer.ref.level == e.value,

lib/src/diff.dart

@@ -10,10 +10,10 @@ class Diff {
   /// Initializes a new instance of [Diff] class from provided
   /// pointer to diff object in memory.
   ///
-  /// Should be freed with `free()` to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Diff(this._diffPointer);
 
-  /// Reads the contents of a git patch file into a git diff object.
+  /// Reads the [content]s of a git patch file into a git diff object.
   ///
   /// The diff object produced is similar to the one that would be produced if you actually
   /// produced it computationally by comparing two trees, however there may be subtle differences.
@@ -32,7 +32,7 @@ class Diff {
   /// Pointer to memory address for allocated diff object.
   Pointer<git_diff> get pointer => _diffPointer;
 
-  /// Queries how many diff records are there in a diff.
+  /// How many diff records are there in a diff.
   int get length => bindings.length(_diffPointer);
 
   /// Returns a list of [DiffDelta]s containing file pairs with and old and new revisions.
@@ -48,7 +48,7 @@ class Diff {
     return deltas;
   }
 
-  /// Returns a list of [Patch]es.
+  /// A List of [Patch]es.
   List<Patch> get patches {
     final length = bindings.length(_diffPointer);
     var patches = <Patch>[];
@@ -58,7 +58,7 @@ class Diff {
     return patches;
   }
 
-  /// Returns a patch diff string.
+  /// The patch diff string.
   String get patch {
     final length = bindings.length(_diffPointer);
     var buffer = calloc<git_buf>(sizeOf<git_buf>());
@@ -98,6 +98,25 @@ class Diff {
   /// with new entries reflecting those changes. This also will, if requested, break modified
   /// files into add/remove pairs if the amount of change is above a threshold.
   ///
+  /// [flags] is a combination of [GitDiffFind] flags. Defaults to [GitDiffFind.byConfig].
+  ///
+  /// [renameThreshold] is the threshold above which similar files will be considered renames.
+  /// This is equivalent to the -M option. Defaults to 50.
+  ///
+  /// [copyThreshold] is the threshold above which similar files will be considered copies.
+  /// This is equivalent to the -C option. Defaults to 50.
+  ///
+  /// [renameFromRewriteThreshold] is the threshold below which similar files will be
+  /// eligible to be a rename source. This is equivalent to the first part of the -B option.
+  /// Defaults to 50.
+  ///
+  /// [breakRewriteThreshold] is the treshold below which similar files will be split into
+  /// a delete/add pair. This is equivalent to the last part of the -B option. Defaults to 60.
+  ///
+  /// [renameLimit] is the maximum number of matches to consider for a particular file.
+  /// This is a little different from the -l option from Git because we will still process
+  /// up to this many matches before abandoning the search. Defaults to 200.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   void findSimilar({
     Set<GitDiffFind> flags = const {GitDiffFind.byConfig},
@@ -145,14 +164,14 @@ class DiffDelta {
   /// Pointer to memory address for allocated diff delta object.
   final Pointer<git_diff_delta> _diffDeltaPointer;
 
-  /// Returns type of change.
+  /// Type of change.
   GitDelta get status {
     return GitDelta.values.singleWhere(
       (e) => _diffDeltaPointer.ref.status == e.value,
     );
   }
 
-  /// Looks up the single character abbreviation for a delta status code.
+  /// Single character abbreviation for a delta status code.
   ///
   /// When you run `git diff --name-status` it uses single letter codes in the output such as
   /// 'A' for added, 'D' for deleted, 'M' for modified, etc. This function converts a [GitDelta]
@@ -160,21 +179,18 @@ class DiffDelta {
   /// a space (i.e. ' ').
   String get statusChar => bindings.statusChar(_diffDeltaPointer.ref.status);
 
-  /// Returns flags for the delta object.
+  /// Flags for the delta object.
   Set<GitDiffFlag> get flags {
     return GitDiffFlag.values
         .where((e) => _diffDeltaPointer.ref.flags & e.value == e.value)
         .toSet();
   }
 
-  /// Returns a similarity score for renamed or copied files between 0 and 100
+  /// Similarity score for renamed or copied files between 0 and 100
   /// indicating how similar the old and new sides are.
-  ///
-  /// The similarity score is zero unless you call `find_similar()` which does
-  /// a similarity analysis of files in the diff.
   int get similarity => _diffDeltaPointer.ref.similarity;
 
-  /// Returns number of files in this delta.
+  /// Number of files in this delta.
   int get numberOfFiles => _diffDeltaPointer.ref.nfiles;
 
   /// Represents the "from" side of the diff.
@@ -201,24 +217,24 @@ class DiffFile {
 
   final git_diff_file _diffFile;
 
-  /// Returns [Oid] of the item. If the entry represents an absent side of a diff
+  /// [Oid] of the item. If the entry represents an absent side of a diff
   /// then the oid will be zeroes.
   Oid get oid => Oid.fromRaw(_diffFile.id);
 
-  /// Returns path to the entry relative to the working directory of the repository.
+  /// Path to the entry relative to the working directory of the repository.
   String get path => _diffFile.path.cast<Utf8>().toDartString();
 
-  /// Returns the size of the entry in bytes.
+  /// Size of the entry in bytes.
   int get size => _diffFile.size;
 
-  /// Returns flags for the diff file object.
+  /// Flags for the diff file object.
   Set<GitDiffFlag> get flags {
     return GitDiffFlag.values
         .where((e) => _diffFile.flags & e.value == e.value)
         .toSet();
   }
 
-  /// Returns one of the [GitFilemode] values.
+  /// One of the [GitFilemode] values.
   GitFilemode get mode {
     return GitFilemode.values.singleWhere((e) => _diffFile.mode == e.value);
   }
@@ -232,21 +248,23 @@ class DiffFile {
 class DiffStats {
   /// Initializes a new instance of [DiffStats] class from provided
   /// pointer to diff stats object in memory.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   const DiffStats(this._diffStatsPointer);
 
   /// Pointer to memory address for allocated diff delta object.
   final Pointer<git_diff_stats> _diffStatsPointer;
 
-  /// Returns the total number of insertions.
+  /// Total number of insertions.
   int get insertions => bindings.statsInsertions(_diffStatsPointer);
 
-  /// Returns the total number of deletions.
+  /// Total number of deletions.
   int get deletions => bindings.statsDeletions(_diffStatsPointer);
 
-  /// Returns the total number of files changed.
+  /// Total number of files changed.
   int get filesChanged => bindings.statsFilesChanged(_diffStatsPointer);
 
-  /// Print diff statistics.
+  /// Prints diff statistics.
   ///
   /// Width for output only affects formatting of [GitDiffStats.full].
   ///
@@ -284,25 +302,25 @@ class DiffHunk {
   /// Pointer to memory address for allocated patch object.
   final Pointer<git_patch> _patchPointer;
 
-  /// Returns count of total lines in this hunk.
+  /// Number of total lines in this hunk.
   final int linesCount;
 
-  /// Returns index of this hunk in the patch.
+  /// Index of this hunk in the patch.
   final int index;
 
-  /// Returns starting line number in 'old file'.
+  /// Starting line number in 'old file'.
   int get oldStart => _diffHunkPointer.ref.old_start;
 
-  /// Returns number of lines in 'old file'.
+  /// Number of lines in 'old file'.
   int get oldLines => _diffHunkPointer.ref.old_lines;
 
-  /// Returns starting line number in 'new file'.
+  /// Starting line number in 'new file'.
   int get newStart => _diffHunkPointer.ref.new_start;
 
-  /// Returns number of lines in 'new file'.
+  /// Number of lines in 'new file'.
   int get newLines => _diffHunkPointer.ref.new_lines;
 
-  /// Returns header of a hunk.
+  /// Header of a hunk.
   String get header {
     var list = <int>[];
     for (var i = 0; i < _diffHunkPointer.ref.header_len; i++) {
@@ -311,7 +329,7 @@ class DiffHunk {
     return String.fromCharCodes(list);
   }
 
-  /// Returns list of lines in a hunk of a patch.
+  /// List of lines in a hunk of a patch.
   List<DiffLine> get lines {
     var lines = <DiffLine>[];
     for (var i = 0; i < linesCount; i++) {
@@ -339,26 +357,26 @@ class DiffLine {
   /// Pointer to memory address for allocated diff line object.
   final Pointer<git_diff_line> _diffLinePointer;
 
-  /// Returns type of the line.
+  /// Type of the line.
   GitDiffLine get origin {
     return GitDiffLine.values.singleWhere(
       (e) => _diffLinePointer.ref.origin == e.value,
     );
   }
 
-  /// Returns line number in old file or -1 for added line.
+  /// Line number in old file or -1 for added line.
   int get oldLineNumber => _diffLinePointer.ref.old_lineno;
 
-  /// Returns line number in new file or -1 for deleted line.
+  /// Line number in new file or -1 for deleted line.
   int get newLineNumber => _diffLinePointer.ref.new_lineno;
 
-  /// Returns number of newline characters in content.
+  /// Number of newline characters in content.
   int get numLines => _diffLinePointer.ref.num_lines;
 
-  /// Returns offset in the original file to the content.
+  /// Offset in the original file to the content.
   int get contentOffset => _diffLinePointer.ref.content_offset;
 
-  /// Returns content of the diff line.
+  /// Content of the diff line.
   String get content =>
       _diffLinePointer.ref.content.cast<Utf8>().toDartString();
 

lib/src/index.dart

@@ -10,7 +10,7 @@ class Index with IterableMixin<IndexEntry> {
   /// Initializes a new instance of [Index] class from provided
   /// pointer to index object in memory.
   ///
-  /// Should be freed with `free()` to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   const Index(this._indexPointer);
 
   final Pointer<git_index> _indexPointer;
@@ -20,7 +20,8 @@ class Index with IterableMixin<IndexEntry> {
 
   /// Returns index entry located at provided 0-based position or string path.
   ///
-  /// Throws error if position is out of bounds or entry isn't found at path.
+  /// Throws [RangeError] when provided [value] is outside of valid range or
+  /// [ArgumentError] if nothing found for provided path.
   IndexEntry operator [](Object value) {
     if (value is int) {
       return IndexEntry(bindings.getByIndex(
@@ -36,7 +37,7 @@ class Index with IterableMixin<IndexEntry> {
     }
   }
 
-  /// Checks whether entry at provided [path] is in the git index or not.
+  /// Whether entry at provided [path] is in the git index or not.
   bool find(String path) {
     return bindings.find(
       indexPointer: _indexPointer,
@@ -44,7 +45,7 @@ class Index with IterableMixin<IndexEntry> {
     );
   }
 
-  /// Checks if the index contains entries representing file conflicts.
+  /// Whether index contains entries representing file conflicts.
   bool get hasConflicts => bindings.hasConflicts(_indexPointer);
 
   /// Returns map of conflicts in the index with key as conflicted file path and
@@ -112,7 +113,7 @@ class Index with IterableMixin<IndexEntry> {
   ///
   /// This method will fail in bare index instances.
   ///
-  /// The `pathspec` is a list of file names or shell glob patterns that will be matched
+  /// The [pathspec] is a list of file names or shell glob patterns that will be matched
   /// against files in the repository's working directory. Each file that matches will be
   /// added to the index (either updating an existing entry or adding a new entry).
   ///
@@ -123,11 +124,11 @@ class Index with IterableMixin<IndexEntry> {
 
   /// Updates the contents of an existing index object in memory by reading from the hard disk.
   ///
-  /// If force is true (default), this performs a "hard" read that discards in-memory changes and
+  /// If [force] is true (default), this performs a "hard" read that discards in-memory changes and
   /// always reloads the on-disk index data. If there is no on-disk version,
   /// the index will be cleared.
   ///
-  /// If force is false, this does a "soft" read that reloads the index data from disk only
+  /// If [force] is false, this does a "soft" read that reloads the index data from disk only
   /// if it has changed since the last time it was loaded. Purely in-memory index data
   /// will be untouched. Be aware: if there are changes on disk, unwritten in-memory changes
   /// are discarded.
@@ -147,11 +148,12 @@ class Index with IterableMixin<IndexEntry> {
   ///
   /// This method will scan the index and write a representation of its current state back to disk;
   /// it recursively creates tree objects for each of the subtrees stored in the index, but only
-  /// returns the [Oid] of the root tree. This is the OID that can be used e.g. to create a commit.
+  /// returns the [Oid] of the root tree. This is the oid that can be used e.g. to create a commit.
   ///
   /// The index must not contain any file in conflict.
   ///
-  /// Throws a [LibGit2Error] if error occured or there is no associated repository and no [repo] passed.
+  /// Throws a [LibGit2Error] if error occured or there is no associated repository
+  /// and no [repo] passed.
   Oid writeTree([Repository? repo]) {
     if (repo == null) {
       return Oid(bindings.writeTree(_indexPointer));
@@ -163,19 +165,29 @@ class Index with IterableMixin<IndexEntry> {
     }
   }
 
-  /// Removes an entry from the index.
+  /// Removes an entry from the index at provided [path] relative to repository working
+  /// directory with optional [stage].
   ///
   /// Throws a [LibGit2Error] if error occured.
   void remove(String path, [int stage = 0]) =>
       bindings.remove(indexPointer: _indexPointer, path: path, stage: stage);
 
-  /// Removes all matching index entries.
+  /// Removes all matching index entries at provided list of [path]s relative to repository
+  /// working directory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   void removeAll(List<String> path) =>
       bindings.removeAll(indexPointer: _indexPointer, pathspec: path);
 
   /// Creates a diff between the repository index and the workdir directory.
+  ///
+  /// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
+  ///
+  /// [contextLines] is the number of unchanged lines that define the boundary
+  /// of a hunk (and to display before and after). Defaults to 3.
+  ///
+  /// [interhunkLines] is the maximum number of unchanged lines between hunk
+  /// boundaries before the hunks will be merged into one. Defaults to 0.
   Diff diffToWorkdir({
     Set<GitDiff> flags = const {GitDiff.normal},
     int contextLines = 3,
@@ -191,6 +203,16 @@ class Index with IterableMixin<IndexEntry> {
   }
 
   /// Creates a diff between a tree and repository index.
+  ///
+  /// [tree] is the [Tree] object to diff from.
+  ///
+  /// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
+  ///
+  /// [contextLines] is the number of unchanged lines that define the boundary
+  /// of a hunk (and to display before and after). Defaults to 3.
+  ///
+  /// [interhunkLines] is the maximum number of unchanged lines between hunk
+  /// boundaries before the hunks will be merged into one. Defaults to 0.
   Diff diffToTree({
     required Tree tree,
     Set<GitDiff> flags = const {GitDiff.normal},
@@ -226,23 +248,18 @@ class IndexEntry {
   /// Pointer to memory address for allocated index entry object.
   Pointer<git_index_entry> get pointer => _indexEntryPointer;
 
-  /// Returns inique identity of the index entry.
+  /// [Oid] of the index entry.
   Oid get oid => Oid.fromRaw(_indexEntryPointer.ref.id);
 
-  /// Sets inique identity of the index entry.
   set oid(Oid oid) => _indexEntryPointer.ref.id = oid.pointer.ref;
 
-  /// Returns path of the index entry.
+  /// Path of the index entry.
   String get path => _indexEntryPointer.ref.path.cast<Utf8>().toDartString();
 
-  /// Sets path of the index entry.
   set path(String path) =>
       _indexEntryPointer.ref.path = path.toNativeUtf8().cast<Int8>();
 
-  /// Returns id of the index entry as sha hex.
+  /// UNIX file attributes of a index entry.
-  String get sha => _oidToHex(_indexEntryPointer.ref.id);
-
-  /// Returns the UNIX file attributes of a index entry.
   GitFilemode get mode {
     return GitFilemode.values.singleWhere(
       (mode) => _indexEntryPointer.ref.mode == mode.value,
@@ -256,14 +273,6 @@ class IndexEntry {
   String toString() {
     return 'IndexEntry{oid: $oid, path: $path, mode: $mode}';
   }
-
-  String _oidToHex(git_oid oid) {
-    var hex = StringBuffer();
-    for (var i = 0; i < 20; i++) {
-      hex.write(oid.id[i].toRadixString(16));
-    }
-    return hex.toString();
-  }
 }
 
 class ConflictEntry {

lib/src/mailmap.dart

@@ -8,7 +8,9 @@ class Mailmap {
   /// Initializes a new instance of [Mailmap] class.
   ///
   /// This object is empty, so you'll have to add a mailmap file before you can
-  /// do anything with it. Must be freed with `free()`.
+  /// do anything with it.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Mailmap.empty() {
     libgit2.git_libgit2_init();
 
@@ -17,14 +19,14 @@ class Mailmap {
 
   /// Initializes a new instance of [Mailmap] class from provided buffer.
   ///
-  /// Must be freed with `free()`.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Mailmap.fromBuffer(String buffer) {
     libgit2.git_libgit2_init();
 
     _mailmapPointer = bindings.fromBuffer(buffer);
   }
 
-  /// Initializes a new instance of [Mailmap] class from a repository, loading
+  /// Initializes a new instance of [Mailmap] class from a [repo]sitory, loading
   /// mailmap files based on the repository's configuration.
   ///
   /// Mailmaps are loaded in the following order:
@@ -34,7 +36,7 @@ class Mailmap {
   ///   NOTE: `mailmap.blob` defaults to `HEAD:.mailmap` in bare repositories
   /// 3. The path in the `mailmap.file` config entry, if set.
   ///
-  /// Must be freed with `free()`.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Mailmap.fromRepository(Repository repo) {
@@ -57,7 +59,7 @@ class Mailmap {
     );
   }
 
-  /// Resolves a signature to use real names and emails with a mailmap.
+  /// Resolves a [signature] to use real names and emails with a mailmap.
   Signature resolveSignature(Signature signature) {
     return Signature(bindings.resolveSignature(
       mailmapPointer: _mailmapPointer,

lib/src/note.dart

@@ -8,10 +8,15 @@ class Note {
   /// pointer to note and annotatedOid objects in memory.
   Note(this._notePointer, this._annotatedOidPointer);
 
-  /// Reads the note for an [annotatedOid].
+  /// Lookups the note for an [annotatedOid].
   ///
-  /// IMPORTANT: Notes must be freed manually when no longer needed to prevent
+  /// [repo] is the repository where to look up the note.
-  /// memory leak.
+  ///
+  /// [annotatedOid] is the [Oid] of the git object to read the note from.
+  ///
+  /// [notesRef] is the canonical name of the reference to use. Defaults to "refs/notes/commits".
+  ///
+  /// **IMPORTANT**: Notes must be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Note.lookup({
@@ -33,7 +38,21 @@ class Note {
   /// Pointer to memory address for allocated annotetedOid object.
   late final Pointer<git_oid> _annotatedOidPointer;
 
-  /// Adds a note for an [annotatedOid].
+  /// Creates a note for an [annotatedOid].
+  ///
+  /// [repo] is the repository where to store the note.
+  ///
+  /// [author] is the signature of the note's commit author.
+  ///
+  /// [committer] is the signature of the note's commit committer.
+  ///
+  /// [annotatedOid] is the [Oid] of the git object to decorate.
+  ///
+  /// [note] is the content of the note to add.
+  ///
+  /// [notesRef] is the canonical name of the reference to use. Defaults to "refs/notes/commits".
+  ///
+  /// [force] determines whether existing note should be overwritten.
   ///
   /// Throws a [LibGit2Error] if error occured.
   static Oid create({
@@ -58,6 +77,16 @@ class Note {
 
   /// Deletes the note for an [annotatedOid].
   ///
+  /// [repo] is the repository where the note lives.
+  ///
+  /// [annotatedOid] is the [Oid] of the git object to remove the note from.
+  ///
+  /// [author] is the signature of the note's commit author.
+  ///
+  /// [committer] is the signature of the note's commit committer.
+  ///
+  /// [notesRef] is the canonical name of the reference to use. Defaults to "refs/notes/commits".
+  ///
   /// Throws a [LibGit2Error] if error occured.
   static void delete({
     required Repository repo,
@@ -74,10 +103,9 @@ class Note {
     );
   }
 
-  /// Returns list of notes for repository.
+  /// Returns list of notes for [repo]sitory.
   ///
-  /// IMPORTANT: Notes must be freed manually when no longer needed to prevent
+  /// **IMPORTANT**: Notes must be freed to release allocated memory.
-  /// memory leak.
   ///
   /// Throws a [LibGit2Error] if error occured.
   static List<Note> list(Repository repo) {
@@ -90,13 +118,13 @@ class Note {
         .toList();
   }
 
-  /// Returns the note object's [Oid].
+  /// Note object's [Oid].
   Oid get oid => Oid(bindings.id(_notePointer));
 
-  /// Returns the note message.
+  /// Note message.
   String get message => bindings.message(_notePointer);
 
-  /// Returns the [Oid] of the git object being annotated.
+  /// [Oid] of the git object being annotated.
   Oid get annotatedOid => Oid(_annotatedOidPointer);
 
   /// Releases memory allocated for note object.

lib/src/odb.dart

@@ -7,13 +7,16 @@ import 'util.dart';
 class Odb {
   /// Initializes a new instance of [Odb] class from provided
   /// pointer to Odb object in memory.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Odb(this._odbPointer);
 
-  /// Initializes a new instance of [Odb] class by creating a new object database with
+  /// Creates a new object database with no backends.
-  /// no backends.
   ///
   /// Before the ODB can be used for read/writing, a custom database backend must be
   /// manually added.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Odb.create() {
     libgit2.git_libgit2_init();
 
@@ -41,12 +44,12 @@ class Odb {
     );
   }
 
-  /// Returns list of all objects [Oid]s available in the database.
+  /// List of all objects [Oid]s available in the database.
   ///
   /// Throws a [LibGit2Error] if error occured.
   List<Oid> get objects => bindings.objects(_odbPointer);
 
-  /// Checks if the given object can be found in the object database.
+  /// Whether given object [oid] can be found in the object database.
   bool contains(Oid oid) {
     return bindings.exists(odbPointer: _odbPointer, oidPointer: oid.pointer);
   }
@@ -55,7 +58,7 @@ class Odb {
   ///
   /// This method queries all available ODB backends trying to read the given [oid].
   ///
-  /// The returned object should be freed by the user once it's no longer in use.
+  /// **IMPORTANT**: Returned object should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   OdbObject read(Oid oid) {
@@ -67,7 +70,7 @@ class Odb {
 
   /// Writes raw [data] to into the object database.
   ///
-  /// [type] should be one of [GitObject.blob], [GitObject.commit], [GitObject.tag],
+  /// [type] should be one of [GitObject.blob], [GitObject.commit], [GitObject.tag] or
   /// [GitObject.tree].
   ///
   /// Throws a [LibGit2Error] if error occured or [ArgumentError] if provided type is invalid.
@@ -98,25 +101,19 @@ class OdbObject {
   /// Pointer to memory address for allocated odbObject object.
   final Pointer<git_odb_object> _odbObjectPointer;
 
-  /// Returns the [Oid] of an ODB object.
+  /// [Oid] of an ODB object.
-  ///
-  /// This is the [Oid] from which the object was read from.
   Oid get oid => Oid(bindings.objectId(_odbObjectPointer));
 
-  /// Returns the type of an ODB object.
+  /// Type of an ODB object.
   GitObject get type {
     final typeInt = bindings.objectType(_odbObjectPointer);
     return GitObject.values.singleWhere((e) => typeInt == e.value);
   }
 
-  /// Returns the data of an ODB object.
+  /// Uncompressed, raw data as read from the ODB, without the leading header.
-  ///
-  /// This is the uncompressed, raw data as read from the ODB, without the leading header.
   String get data => bindings.objectData(_odbObjectPointer);
 
-  /// Returns the size of an ODB object.
+  /// Real size of the `data` buffer, not the actual size of the object.
-  ///
-  /// This is the real size of the `data` buffer, not the actual size of the object.
   int get size => bindings.objectSize(_odbObjectPointer);
 
   /// Releases memory allocated for odbObject object.

lib/src/oid.dart

@@ -35,7 +35,7 @@ class Oid {
     }
   }
 
-  /// Initializes a new instance of [Oid] class from provided raw git_oid.
+  /// Initializes a new instance of [Oid] class from provided raw git_oid structure.
   Oid.fromRaw(git_oid raw) {
     _oidPointer = bindings.fromRaw(raw.id);
   }
@@ -45,7 +45,7 @@ class Oid {
   /// Pointer to memory address for allocated oid object.
   Pointer<git_oid> get pointer => _oidPointer;
 
-  /// Returns hexadecimal SHA string.
+  /// Hexadecimal SHA string.
   String get sha => bindings.toSHA(_oidPointer);
 
   @override

lib/src/packbuilder.dart

@@ -6,7 +6,7 @@ import 'bindings/packbuilder.dart' as bindings;
 class PackBuilder {
   /// Initializes a new instance of [PackBuilder] class.
   ///
-  /// Should be freed with `free()`.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   PackBuilder(Repository repo) {
@@ -49,15 +49,15 @@ class PackBuilder {
     bindings.write(packbuilderPointer: _packbuilderPointer, path: path);
   }
 
-  /// Returns the total number of objects the packbuilder will write out.
+  /// Total number of objects the packbuilder will write out.
   int get length => bindings.length(_packbuilderPointer);
 
-  /// Returns the number of objects the packbuilder has already written out.
+  /// Number of objects the packbuilder has already written out.
   int get writtenLength => bindings.writtenCount(_packbuilderPointer);
 
   /// Sets and returns the number of threads to spawn.
   ///
-  /// By default, libgit2 won't spawn any threads at all; when set to 0,
+  /// By default, libgit2 won't spawn any threads at all. When set to 0,
   /// libgit2 will autodetect the number of CPUs.
   int setThreads(int number) {
     return bindings.setThreads(

lib/src/patch.dart

@@ -9,7 +9,7 @@ class Patch {
   /// Initializes a new instance of [Patch] class from provided
   /// pointer to patch object in memory and pointers to old and new blobs/buffers.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Patch(this._patchPointer, this._aPointer, this._bPointer);
 
   /// Directly generates a patch from the difference between two blobs, buffers or
@@ -17,7 +17,19 @@ class Patch {
   ///
   /// [a] and [b] can be [Blob], [String] or null.
   ///
-  /// Should be freed to release allocated memory.
+  /// [aPath] treat [a] as if it had this filename, can be null.
+  ///
+  /// [bPath] treat [b] as if it had this filename, can be null.
+  ///
+  /// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
+  ///
+  /// [contextLines] is the number of unchanged lines that define the boundary
+  /// of a hunk (and to display before and after). Defaults to 3.
+  ///
+  /// [interhunkLines] is the maximum number of unchanged lines between hunk
+  /// boundaries before the hunks will be merged into one. Defaults to 0.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Patch.create({
     required Object? a,
     required Object? b,
@@ -75,9 +87,13 @@ class Patch {
     _bPointer = result['b'];
   }
 
-  /// Returns a patch for an entry in the diff list.
+  /// Creates a patch for an entry in the diff list.
   ///
-  /// Should be freed with `free()` to release allocated memory.
+  /// [diff] is the [Diff] list object.
+  ///
+  /// [index] is the position of an entry in diff list.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Patch.fromDiff({required Diff diff, required int index}) {
@@ -94,12 +110,12 @@ class Patch {
   /// Pointer to memory address for allocated patch object.
   Pointer<git_patch> get pointer => _patchPointer;
 
-  /// Returns the content of a patch as a single diff text.
+  /// Content of a patch as a single diff text.
   ///
   /// Throws a [LibGit2Error] if error occured.
   String get text => bindings.text(_patchPointer);
 
-  /// Looks up size of patch diff data in bytes.
+  /// Size of patch diff data in bytes.
   ///
   /// This returns the raw size of the patch data. This only includes the actual data from
   /// the lines of the diff, not the file or hunk headers.
@@ -107,6 +123,9 @@ class Patch {
   /// If you pass `includeContext` as true, this will be the size of all of the diff output;
   /// if you pass it as false, this will only include the actual changed lines (as if
   /// contextLines was 0).
+  ///
+  /// If [includeHunkHeaders] and [includeFileHeaders] are set to true, they will be included
+  /// in the total size.
   int size({
     bool includeContext = false,
     bool includeHunkHeaders = false,
@@ -120,10 +139,10 @@ class Patch {
     );
   }
 
-  /// Returns the delta associated with a patch.
+  /// Delta associated with a patch.
   DiffDelta get delta => DiffDelta(bindings.delta(_patchPointer));
 
-  /// Returns the list of hunks in a patch.
+  /// List of hunks in a patch.
   List<DiffHunk> get hunks {
     final length = bindings.numHunks(_patchPointer);
     final hunks = <DiffHunk>[];

lib/src/rebase.dart

@@ -4,10 +4,8 @@ import 'bindings/libgit2_bindings.dart';
 import 'bindings/rebase.dart' as bindings;
 
 class Rebase {
-  /// Initializes a new instance of the [Rebase] class by initializing a
+  /// Initializes a rebase operation to rebase the changes in [branch] relative to [upstream]
-  /// rebase operation to rebase the changes in [branch] relative to [upstream]
+  /// [onto] another branch. To begin the rebase process, call [next].
-  /// [onto] another branch. To begin the rebase process, call `next()`.
-  /// When you have finished with this object, call `free()`.
   ///
   /// [branch] is the terminal commit to rebase, default is to rebase the current branch.
   ///
@@ -17,6 +15,8 @@ class Rebase {
   /// [onto] is the branch to rebase onto, default is to rebase onto the given [upstream]
   /// (throws if [upstream] is not provided).
   ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   Rebase.init({
     required Repository repo,
@@ -56,7 +56,7 @@ class Rebase {
   /// Pointer to memory address for allocated rebase object.
   late final Pointer<git_rebase> _rebasePointer;
 
-  /// The count of rebase operations that are to be applied.
+  /// Number of rebase operations that are to be applied.
   int get operationsCount {
     return bindings.operationsCount(_rebasePointer);
   }
@@ -75,6 +75,14 @@ class Rebase {
   /// Commits the current patch. You must have resolved any conflicts that were
   /// introduced during the patch application from the [next] invocation.
   ///
+  /// [committer] is the committer of the rebase.
+  ///
+  /// [message] the message for this commit, can be null to use the message from the
+  /// original commit.
+  ///
+  /// [author] is the author of the updated commit, can be null to keep the author from
+  /// the original commit.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   void commit({
     required Signature committer,
@@ -108,14 +116,14 @@ class RebaseOperation {
   /// Pointer to memory address for allocated rebase operation object.
   final Pointer<git_rebase_operation> _rebaseOperationPointer;
 
-  /// Returns the type of rebase operation.
+  /// Type of rebase operation.
   GitRebaseOperation get type {
     return GitRebaseOperation.values.singleWhere(
       (e) => _rebaseOperationPointer.ref.type == e.value,
     );
   }
 
-  /// Returns the commit [Oid] being cherry-picked.
+  /// [Oid] of commit being cherry-picked.
   Oid get oid => Oid.fromRaw(_rebaseOperationPointer.ref.id);
 
   @override

lib/src/reference.dart

@@ -8,19 +8,21 @@ import 'bindings/repository.dart' as repository_bindings;
 
 class Reference {
   /// Initializes a new instance of the [Reference] class.
-  /// Should be freed to release allocated memory.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Reference(this._refPointer);
 
-  /// Creates a new reference.
+  /// Creates a new reference for provided [target].
   ///
   /// The reference will be created in the [repo]sitory and written to the disk.
-  /// The generated [Reference] object must be freed by the user.
+  ///
+  /// **IMPORTANT**: The generated [Reference] object should be freed to release
+  /// allocated memory.
   ///
   /// Valid reference [name]s must follow one of two patterns:
-  ///
+  /// - Top-level names must contain only capital letters and underscores, and must begin and end
-  /// Top-level names must contain only capital letters and underscores, and must begin and end
   /// with a letter. (e.g. "HEAD", "ORIG_HEAD").
-  /// Names prefixed with "refs/" can be almost anything. You must avoid the characters
+  /// - Names prefixed with "refs/" can be almost anything. You must avoid the characters
   /// '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have
   /// special meaning to revparse.
   ///
@@ -63,7 +65,7 @@ class Reference {
 
   /// Lookups reference [name] in a [repo]sitory.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// The [name] will be checked for validity.
   ///
@@ -86,7 +88,7 @@ class Reference {
     ref.free();
   }
 
-  /// Renames an existing reference.
+  /// Renames an existing reference with provided [oldName].
   ///
   /// This method works for both direct and symbolic references.
   ///
@@ -116,7 +118,7 @@ class Reference {
     ref.free();
   }
 
-  /// Returns a list of all the references that can be found in a [repo]sitory.
+  /// List of all the references that can be found in a [repo]sitory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   static List<String> list(Repository repo) => bindings.list(repo.pointer);
@@ -132,14 +134,14 @@ class Reference {
     refdb_bindings.free(refdb);
   }
 
-  /// Returns the type of the reference.
+  /// Type of the reference.
   ReferenceType get type {
     return bindings.referenceType(_refPointer) == 1
         ? ReferenceType.direct
         : ReferenceType.symbolic;
   }
 
-  /// Returns the [Oid] pointed to by a reference.
+  /// [Oid] pointed to by a reference.
   ///
   /// Throws an [Exception] if error occured.
   Oid get target {
@@ -155,11 +157,11 @@ class Reference {
 
   /// Updates the [target] of this reference.
   ///
-  /// [target] being either Oid for direct reference or String reference name for symbolic
+  /// [target] being either Oid for direct reference or string reference name for symbolic
   /// reference.
   ///
   /// Throws a [LibGit2Error] if error occured or [ArgumentError] if [target] is not
-  /// [Oid] or String.
+  /// [Oid] or string.
   void setTarget({required Object target, String? logMessage}) {
     if (target is Oid) {
       final newPointer = bindings.setTarget(
@@ -214,16 +216,16 @@ class Reference {
     }
   }
 
-  /// Returns the full name of a reference.
+  /// Full name of a reference.
   String get name => bindings.name(_refPointer);
 
-  /// Returns the reference's short name.
+  /// Reference's short name.
   ///
   /// This will transform the reference name into a name "human-readable" version.
   /// If no shortname is appropriate, it will return the full name.
   String get shorthand => bindings.shorthand(_refPointer);
 
-  /// Checks if a reflog exists for the specified reference [name].
+  /// Whether reflog exists for the specified reference [name].
   bool get hasLog {
     return bindings.hasLog(
       repoPointer: bindings.owner(_refPointer),
@@ -231,24 +233,24 @@ class Reference {
     );
   }
 
-  /// Returns a [RefLog] object.
+  /// [RefLog] object.
   ///
-  /// Should be freed when no longer needed.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   RefLog get log => RefLog(this);
 
-  /// Checks if a reference is a local branch.
+  /// Whether reference is a local branch.
   bool get isBranch => bindings.isBranch(_refPointer);
 
-  /// Checks if a reference is a note.
+  /// Whether reference is a note.
   bool get isNote => bindings.isNote(_refPointer);
 
-  /// Check if a reference is a remote tracking branch.
+  /// Whether reference is a remote tracking branch.
   bool get isRemote => bindings.isRemote(_refPointer);
 
-  /// Check if a reference is a tag.
+  /// Whether reference is a tag.
   bool get isTag => bindings.isTag(_refPointer);
 
-  /// Returns the repository where a reference resides.
+  /// Repository where a reference resides.
   Repository get owner => Repository(bindings.owner(_refPointer));
 
   @override

lib/src/reflog.dart

@@ -6,6 +6,8 @@ import 'bindings/reflog.dart' as bindings;
 
 class RefLog with IterableMixin<RefLogEntry> {
   /// Initializes a new instance of [RefLog] class from provided [Reference].
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   RefLog(Reference ref) {
     _reflogPointer = bindings.read(
       repoPointer: ref.owner.pointer,
@@ -16,10 +18,10 @@ class RefLog with IterableMixin<RefLogEntry> {
   /// Pointer to memory address for allocated reflog object.
   late final Pointer<git_reflog> _reflogPointer;
 
-  /// Lookup an entry by its index.
+  /// Lookups an entry by its index.
   ///
-  /// Requesting the reflog entry with an index of 0 (zero) will return
+  /// Requesting the reflog entry with an index of 0 will return the most
-  /// the most recently created entry.
+  /// recently created entry.
   RefLogEntry operator [](int index) {
     return RefLogEntry(bindings.getByIndex(
       reflogPointer: _reflogPointer,
@@ -35,16 +37,17 @@ class RefLog with IterableMixin<RefLogEntry> {
 }
 
 class RefLogEntry {
-  /// Initializes a new instance of [RefLogEntry] class.
+  /// Initializes a new instance of [RefLogEntry] class from provided
+  /// pointer to RefLogEntry object in memory.
   const RefLogEntry(this._entryPointer);
 
   /// Pointer to memory address for allocated reflog entry object.
   final Pointer<git_reflog_entry> _entryPointer;
 
-  /// Returns the log message.
+  /// Log message.
   String get message => bindings.entryMessage(_entryPointer);
 
-  /// Returns the committer of this entry.
+  /// Committer of this entry.
   Signature get committer => Signature(bindings.entryCommiter(_entryPointer));
 
   @override

lib/src/refspec.dart

@@ -11,26 +11,26 @@ class Refspec {
   /// Pointer to memory address for allocated refspec object.
   final Pointer<git_refspec> _refspecPointer;
 
-  /// Returns the source specifier.
+  /// Source specifier.
   String get source => bindings.source(_refspecPointer);
 
-  /// Returns the destination specifier.
+  /// Destination specifier.
   String get destination => bindings.destination(_refspecPointer);
 
-  /// Returns the force update setting.
+  /// Force update setting.
   bool get force => bindings.force(_refspecPointer);
 
-  /// Returns the refspec's string.
+  /// Refspec's string.
   String get string => bindings.string(_refspecPointer);
 
-  /// Returns the refspec's direction (fetch or push).
+  /// Refspec's direction (fetch or push).
   GitDirection get direction {
     return bindings.direction(_refspecPointer) == 0
         ? GitDirection.fetch
         : GitDirection.push;
   }
 
-  /// Checks if a refspec's source descriptor matches a reference.
+  /// Whether refspec's source descriptor matches a reference.
   bool matchesSource(String refname) {
     return bindings.matchesSource(
       refspecPointer: _refspecPointer,
@@ -38,7 +38,7 @@ class Refspec {
     );
   }
 
-  /// Checks if a refspec's destination descriptor matches a reference.
+  /// Whether refspec's destination descriptor matches a reference.
   bool matchesDestination(String refname) {
     return bindings.matchesDestination(
       refspecPointer: _refspecPointer,

lib/src/remote.dart

@@ -4,19 +4,21 @@ import 'bindings/libgit2_bindings.dart';
 import 'bindings/remote.dart' as bindings;
 
 class Remote {
-  /// Initializes a new instance of [Remote] class by looking up remote with
+  /// Lookups remote with provided [name] in a [repo]sitory.
-  /// provided [name] in a [repo]sitory.
   ///
-  /// The name will be checked for validity.
+  /// The [name] will be checked for validity.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Remote.lookup({required Repository repo, required String name}) {
     _remotePointer = bindings.lookup(repoPointer: repo.pointer, name: name);
   }
 
-  /// Initializes a new instance of [Remote] class by adding a remote with
+  /// Adds remote with provided [name] and [url] to the [repo]sitory's
-  /// provided [name] and [url] to the [repo]sitory's configuration with the
+  /// configuration with the default [fetch] refspec if none provided.
-  /// default [fetch] refspec if none provided .
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Remote.create({
@@ -46,7 +48,7 @@ class Remote {
   /// Pointer to memory address for allocated remote object.
   Pointer<git_remote> get pointer => _remotePointer;
 
-  /// Deletes an existing persisted remote.
+  /// Deletes an existing persisted remote with provided [name].
   ///
   /// All remote-tracking branches and configuration settings for the remote will be removed.
   ///
@@ -55,13 +57,13 @@ class Remote {
     bindings.delete(repoPointer: repo.pointer, name: name);
   }
 
-  /// Gives the remote a new name.
+  /// Renames remote with provided [oldName].
   ///
   /// Returns list of non-default refspecs that cannot be renamed.
   ///
   /// All remote-tracking branches and configuration settings for the remote are updated.
   ///
-  /// The new name will be checked for validity.
+  /// The [newName] will be checked for validity.
   ///
   /// No loaded instances of a the remote with the old name will change their name or
   /// their list of refspecs.
@@ -84,7 +86,7 @@ class Remote {
     return bindings.list(repo.pointer);
   }
 
-  /// Sets the remote's url in the configuration.
+  /// Sets the [remote]'s [url] in the configuration.
   ///
   /// Remote objects already in memory will not be affected. This assumes the common
   /// case of a single-url remote and will otherwise return an error.
@@ -102,7 +104,7 @@ class Remote {
     );
   }
 
-  /// Sets the remote's url for pushing in the configuration.
+  /// Sets the [remote]'s [url] for pushing in the configuration.
   ///
   /// Remote objects already in memory will not be affected. This assumes the common
   /// case of a single-url remote and will otherwise return an error.
@@ -120,7 +122,7 @@ class Remote {
     );
   }
 
-  /// Adds a fetch refspec to the remote's configuration.
+  /// Adds a fetch [refspec] to the [remote]'s configuration.
   ///
   /// No loaded remote instances will be affected.
   ///
@@ -137,7 +139,7 @@ class Remote {
     );
   }
 
-  /// Adds a push refspec to the remote's configuration.
+  /// Adds a push [refspec] to the [remote]'s configuration.
   ///
   /// No loaded remote instances will be affected.
   ///
@@ -154,21 +156,21 @@ class Remote {
     );
   }
 
-  /// Returns the remote's name.
+  /// Remote's name.
   String get name => bindings.name(_remotePointer);
 
-  /// Returns the remote's url.
+  /// Remote's url.
   String get url => bindings.url(_remotePointer);
 
-  /// Returns the remote's url for pushing.
+  /// Remote's url for pushing.
   ///
   /// Returns empty string if no special url for pushing is set.
   String get pushUrl => bindings.pushUrl(_remotePointer);
 
-  /// Returns the number of refspecs for a remote.
+  /// Number of refspecs for a remote.
   int get refspecCount => bindings.refspecCount(_remotePointer);
 
-  /// Returns a [Refspec] object from the remote at provided position.
+  /// [Refspec] object from the remote at provided position.
   Refspec getRefspec(int index) {
     return Refspec(bindings.getRefspec(
       remotePointer: _remotePointer,
@@ -176,10 +178,10 @@ class Remote {
     ));
   }
 
-  /// Returns the remote's list of fetch refspecs.
+  /// List of fetch refspecs.
   List<String> get fetchRefspecs => bindings.fetchRefspecs(_remotePointer);
 
-  /// Get the remote's list of push refspecs.
+  /// List of push refspecs.
   List<String> get pushRefspecs => bindings.pushRefspecs(_remotePointer);
 
   /// Returns the remote repository's reference list and their associated commit ids.
@@ -187,6 +189,8 @@ class Remote {
   /// [proxy] can be 'auto' to try to auto-detect the proxy from the git configuration or some
   /// specified url. By default connection isn't done through proxy.
   ///
+  /// [callbacks] is the combination of callback functions from [Callbacks] object.
+  ///
   /// Returned map keys:
   /// - `local` is true if remote head is available locally, false otherwise.
   /// - `loid` is the oid of the object the local copy of the remote head is currently
@@ -213,10 +217,16 @@ class Remote {
 
   /// Downloads new data and updates tips.
   ///
+  /// [refspecs] is the list of refspecs to use for this fetch. Defaults to the base refspecs.
+  ///
+  /// [reflogMessage] is the message to insert into the reflogs. Default is "fetch".
+  ///
+  /// [prune] determines whether to perform a prune after the fetch.
+  ///
   /// [proxy] can be 'auto' to try to auto-detect the proxy from the git configuration or some
   /// specified url. By default connection isn't done through proxy.
   ///
-  /// [reflogMessage] is the message to insert into the reflogs. Default is "fetch".
+  /// [callbacks] is the combination of callback functions from [Callbacks] object.
   ///
   /// Throws a [LibGit2Error] if error occured.
   TransferProgress fetch({
@@ -239,9 +249,16 @@ class Remote {
 
   /// Performs a push.
   ///
+  /// [refspecs] is the list of refspecs to use for pushing. Defaults to the configured refspecs.
+  ///
+  /// [proxy] can be 'auto' to try to auto-detect the proxy from the git configuration or some
+  /// specified url. By default connection isn't done through proxy.
+  ///
+  /// [callbacks] is the combination of callback functions from [Callbacks] object.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   void push({
-    required List<String> refspecs,
+    List<String> refspecs = const [],
     String? proxy,
     Callbacks callbacks = const Callbacks(),
   }) {
@@ -255,6 +272,8 @@ class Remote {
 
   /// Prunes tracking refs that are no longer present on remote.
   ///
+  /// [callbacks] is the combination of callback functions from [Callbacks] object.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   void prune([Callbacks callbacks = const Callbacks()]) {
     bindings.prune(
@@ -282,25 +301,25 @@ class TransferProgress {
   /// Pointer to memory address for allocated transfer progress object.
   final Pointer<git_indexer_progress> _transferProgressPointer;
 
-  /// Returns total number of objects to download.
+  /// Total number of objects to download.
   int get totalObjects => _transferProgressPointer.ref.total_objects;
 
-  /// Returns number of objects that have been indexed.
+  /// Number of objects that have been indexed.
   int get indexedObjects => _transferProgressPointer.ref.indexed_objects;
 
-  /// Returns number of objects that have been downloaded.
+  /// Number of objects that have been downloaded.
   int get receivedObjects => _transferProgressPointer.ref.received_objects;
 
-  /// Returns number of local objects that have been used to fix the thin pack.
+  /// Number of local objects that have been used to fix the thin pack.
   int get localObjects => _transferProgressPointer.ref.local_objects;
 
-  /// Returns total number of deltas in the pack.
+  /// Total number of deltas in the pack.
   int get totalDeltas => _transferProgressPointer.ref.total_deltas;
 
-  /// Returns number of deltas that have been indexed.
+  /// Number of deltas that have been indexed.
   int get indexedDeltas => _transferProgressPointer.ref.indexed_deltas;
 
-  /// Returns number of bytes received up to now.
+  /// Number of bytes received up to now.
   int get receivedBytes => _transferProgressPointer.ref.received_bytes;
 
   @override

lib/src/revparse.dart

@@ -13,7 +13,7 @@ class RevParse {
   /// intermediate reference. When such expressions are being passed in, reference_out will be
   /// valued as well.
   ///
-  /// The returned object and reference should be released when no longer needed.
+  /// **IMPORTANT**: The returned object and reference should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   RevParse.ext({required Repository repo, required String spec}) {
@@ -78,10 +78,14 @@ class RevSpec {
   /// Pointer to memory address for allocated revspec object.
   final Pointer<git_revspec> _revSpecPointer;
 
-  /// The left element of the revspec; must be freed by the user.
+  /// Left element of the revspec.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Commit get from => Commit(_revSpecPointer.ref.from.cast());
 
-  /// The right element of the revspec; must be freed by the user.
+  /// Right element of the revspec.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Commit? get to {
     return _revSpecPointer.ref.to == nullptr
         ? null

lib/src/revwalk.dart

@@ -5,7 +5,8 @@ import 'bindings/revwalk.dart' as bindings;
 
 class RevWalk {
   /// Initializes a new instance of the [RevWalk] class.
-  /// Should be freed with `free()` to release allocated memory.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   RevWalk(Repository repo) {
     _revWalkPointer = bindings.create(repo.pointer);
   }
@@ -25,7 +26,8 @@ class RevWalk {
     return pointers.map((e) => Commit(e)).toList();
   }
 
-  /// Changes the sorting mode when iterating through the repository's contents.
+  /// Changes the sorting mode when iterating through the repository's contents
+  /// to provided [sorting] combination of [GitSort] modes.
   ///
   /// Changing the sorting mode resets the walker.
   void sorting(Set<GitSort> sorting) {

lib/src/signature.dart

@@ -9,15 +9,15 @@ class Signature {
   /// Initializes a new instance of [Signature] class from provided pointer to
   /// signature object in memory.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Signature(this._signaturePointer);
 
-  /// Initializes a new instance of [Signature] class from provided [name], [email],
+  /// Creates new [Signature] from provided [name], [email], and optional [time]
-  /// and optional [time] in seconds from epoch and [offset] in minutes.
+  /// in seconds from epoch and [offset] in minutes.
   ///
   /// If [time] isn't provided [Signature] will be created with a timestamp of 'now'.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Signature.create({
     required String name,
     required String email,
@@ -50,16 +50,16 @@ class Signature {
   static Signature defaultSignature(Repository repo) =>
       Signature(bindings.defaultSignature(repo.pointer));
 
-  /// Returns full name of the author.
+  /// Full name of the author.
   String get name => _signaturePointer.ref.name.cast<Utf8>().toDartString();
 
-  /// Returns email of the author.
+  /// Email of the author.
   String get email => _signaturePointer.ref.email.cast<Utf8>().toDartString();
 
-  /// Returns time in seconds from epoch.
+  /// Time in seconds from epoch.
   int get time => _signaturePointer.ref.when.time;
 
-  /// Returns timezone offset in minutes.
+  /// Timezone offset in minutes.
   int get offset => _signaturePointer.ref.when.offset;
 
   @override

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,
+    Set<GitStash> flags = const {GitStash.defaults},
-    bool includeUntracked = false,
-    bool includeIgnored = false,
   }) {
-    int flags = 0;
+    final int flagsInt = flags.fold(0, (acc, e) => acc | e.value);
-    if (keepIndex) flags |= GitStash.keepIndex.value;
-    if (includeUntracked) flags |= GitStash.includeUntracked.value;
-    if (includeIgnored) flags |= GitStash.includeIgnored.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,

lib/src/submodule.dart

@@ -4,31 +4,31 @@ import 'bindings/libgit2_bindings.dart';
 import 'bindings/submodule.dart' as bindings;
 
 class Submodule {
-  /// Initializes a new instance of [Submodule] class by looking up
+  /// Lookups submodule information by [name] or path (they are usually the same).
-  /// submodule information by name or path.
   ///
-  /// Given either the submodule name or path (they are usually the same), this
+  /// **IMPORTANT**: Should be freed to release allocated memory.
-  /// returns a structure describing the submodule.
-  ///
-  /// You must call [free] when done with the submodule.
   ///
   /// Throws a [LibGit2Error] if error occured.
-  Submodule.lookup({required Repository repo, required String submodule}) {
+  Submodule.lookup({required Repository repo, required String name}) {
     _submodulePointer = bindings.lookup(
       repoPointer: repo.pointer,
-      name: submodule,
+      name: name,
     );
   }
 
   /// Adds a submodule to the index.
   ///
-  /// [url] is URL for the submodule's remote.
+  /// [url] is the URL for the submodule's remote.
   ///
-  /// [path] is path at which the submodule should be created.
+  /// [path] is the path at which the submodule should be created.
   ///
-  /// [link] determines if workdir should contain a gitlink to the repo in `.git/modules`
+  /// [useGitLink] determines if workdir should contain a gitlink to the repo in `.git/modules`
   /// vs. repo directly in workdir. Default is true.
   ///
+  /// [callbacks] is the combination of callback functions from [Callbacks] object.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   Submodule.add({
     required Repository repo,
@@ -55,7 +55,7 @@ class Submodule {
   /// Copies submodule info into ".git/config" file.
   ///
   /// Just like `git submodule init`, this copies information about the
-  /// submodule into `.git/config`.
+  /// submodule into ".git/config".
   ///
   /// By default, existing entries will not be overwritten, but setting [overwrite]
   /// to true forces them to be updated.
@@ -112,10 +112,12 @@ class Submodule {
 
   /// Opens the repository for a submodule.
   ///
-  /// This is a newly opened repository object. The caller is responsible for freeing it
+  /// Multiple calls to this function will return distinct git repository objects.
-  /// when done. Multiple calls to this function will return distinct git repository objects.
+  ///
   /// This will only work if the submodule is checked out into the working directory.
   ///
+  /// **IMPORTANT**: Returned [Repository] object should be freed to release allocated memory.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   Repository open() {
     return Repository(bindings.open(_submodulePointer));
@@ -158,16 +160,16 @@ class Submodule {
     bindings.reload(submodulePointer: _submodulePointer, force: force);
   }
 
-  /// Returns the name of submodule.
+  /// Name of submodule.
   String get name => bindings.name(_submodulePointer);
 
-  /// Returns the path to the submodule.
+  /// Path to the submodule.
   ///
   /// The path is almost always the same as the submodule name, but the two
   /// are actually not required to match.
   String get path => bindings.path(_submodulePointer);
 
-  /// Returns the URL for the submodule.
+  /// URL for the submodule.
   String get url => bindings.url(_submodulePointer);
 
   /// Sets the URL for the submodule in the configuration.
@@ -182,7 +184,7 @@ class Submodule {
     );
   }
 
-  /// Returns the branch for the submodule.
+  /// Branch for the submodule.
   String get branch => bindings.branch(_submodulePointer);
 
   /// Sets the branch for the submodule in the configuration.
@@ -197,22 +199,21 @@ class Submodule {
     );
   }
 
-  /// Returns the [Oid] for the submodule in the current HEAD tree or
+  /// [Oid] for the submodule in the current HEAD tree or null if submodule is not
-  /// null if submodule is not in the HEAD.
+  /// in the HEAD.
   Oid? get headOid {
     final result = bindings.headId(_submodulePointer);
     return result == null ? null : Oid(result);
   }
 
-  /// Returns the [Oid] for the submodule in the index or null if submodule
+  /// [Oid] for the submodule in the index or null if submodule is not in the index.
-  /// is not in the index.
   Oid? get indexOid {
     final result = bindings.indexId(_submodulePointer);
     return result == null ? null : Oid(result);
   }
 
-  /// Returns the [Oid] for the submodule in the current working directory or null if
+  /// [Oid] for the submodule in the current working directory or null if submodule
-  /// submodule is not checked out.
+  /// is not checked out.
   ///
   /// This returns the [Oid] that corresponds to looking up `HEAD` in the checked out
   /// submodule. If there are pending changes in the index or anything else, this
@@ -223,7 +224,7 @@ class Submodule {
     return result == null ? null : Oid(result);
   }
 
-  /// Returns the ignore rule that will be used for the submodule.
+  /// Ignore rule that will be used for the submodule.
   GitSubmoduleIgnore get ignore {
     final ruleInt = bindings.ignore(_submodulePointer);
     return GitSubmoduleIgnore.values.singleWhere((e) => ruleInt == e.value);
@@ -237,7 +238,7 @@ class Submodule {
     bindings.setIgnore(repoPointer: repo, name: name, ignore: ignore.value);
   }
 
-  /// Returns the update rule that will be used for the submodule.
+  /// Update rule that will be used for the submodule.
   ///
   /// This value controls the behavior of the `git submodule update` command.
   GitSubmoduleUpdate get updateRule {

lib/src/tag.dart

@@ -8,12 +8,12 @@ class Tag {
   /// Initializes a new instance of [Tag] class from provided pointer to
   /// tag object in memory.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Tag(this._tagPointer);
 
   /// Lookups tag object for provided [oid] in a [repo]sitory.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Tag.lookup({required Repository repo, required Oid oid}) {
     _tagPointer = bindings.lookup(
       repoPointer: repo.pointer,
@@ -31,10 +31,25 @@ class Tag {
   ///
   /// The [message] will not be cleaned up.
   ///
-  /// The tag name will be checked for validity. You must avoid the characters
+  /// The [tagName] will be checked for validity. You must avoid the characters
   /// '~', '^', ':', '\', '?', '[', and '*', and the sequences ".." and "@{" which have
   /// special meaning to revparse.
   ///
+  /// [repo] is the repository where to store the tag.
+  ///
+  /// [tagName] is the name for the tag. This name is validated for consistency. It should
+  /// also not conflict with an already existing tag name.
+  ///
+  /// [target] is the object to which this tag points. This object must belong to the given [repo].
+  ///
+  /// [targetType] is one of the [GitObject] basic types: commit, tree, blob or tag.
+  ///
+  /// [tagger] is the signature of the tagger for this tag, and of the tagging time.
+  ///
+  /// [message] is the full message for this tag.
+  ///
+  /// [force] determines whether existing reference with the same [tagName] should be replaced.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   static Oid create({
     required Repository repo,
@@ -81,7 +96,7 @@ class Tag {
     return bindings.list(repo.pointer);
   }
 
-  /// Get the tagged object (commit, tree, blob, tag) of a tag.
+  /// Tagged object (commit, tree, blob, tag) of a tag.
   ///
   /// This method performs a repository lookup for the given object and returns it.
   ///
@@ -110,16 +125,16 @@ class Tag {
     }
   }
 
-  /// Returns the [Oid] of a tag.
+  /// [Oid] of a tag.
   Oid get oid => Oid(bindings.id(_tagPointer));
 
-  /// Returns the name of a tag.
+  /// Name of a tag.
   String get name => bindings.name(_tagPointer);
 
-  /// Returns the message of a tag.
+  /// Message of a tag.
   String get message => bindings.message(_tagPointer);
 
-  /// Returns the tagger (author) of a tag if there is one.
+  /// Tagger (author) of a tag if there is one.
   Signature? get tagger {
     final sigPointer = bindings.tagger(_tagPointer);
     if (sigPointer != nullptr) {

lib/src/tree.dart

@@ -8,12 +8,12 @@ class Tree {
   /// Initializes a new instance of [Tree] class from provided pointer to
   /// tree object in memory.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Tree(this._treePointer);
 
   /// Lookups a tree object for provided [oid] in a [repo]sitory.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   Tree.lookup({required Repository repo, required Oid oid}) {
     _treePointer = bindings.lookup(
       repoPointer: repo.pointer,
@@ -26,7 +26,7 @@ class Tree {
   /// Pointer to memory address for allocated tree object.
   Pointer<git_tree> get pointer => _treePointer;
 
-  /// Returns a list with tree entries of a tree.
+  /// List with tree entries of a tree.
   List<TreeEntry> get entries {
     final entryCount = bindings.entryCount(_treePointer);
     var result = <TreeEntry>[];
@@ -47,6 +47,8 @@ class Tree {
   /// If string [value] is provided, lookup is done by entry filename.
   ///
   /// If provided string [value] is a path to file, lookup is done by path.
+  ///
+  /// Throws [ArgumentError] if provided [value] is not int or string.
   TreeEntry operator [](Object value) {
     if (value is int) {
       return TreeEntry(bindings.getByIndex(
@@ -69,14 +71,22 @@ class Tree {
     }
   }
 
-  /// Returns the [Oid] of a tree.
+  /// [Oid] of a tree.
   Oid get oid => Oid(bindings.id(_treePointer));
 
-  /// Get the number of entries listed in a tree.
+  /// Number of entries listed in a tree.
   int get length => bindings.entryCount(_treePointer);
 
   /// Creates a diff between a tree and the working directory.
   ///
+  /// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
+  ///
+  /// [contextLines] is the number of unchanged lines that define the boundary
+  /// of a hunk (and to display before and after). Defaults to 3.
+  ///
+  /// [interhunkLines] is the maximum number of unchanged lines between hunk
+  /// boundaries before the hunks will be merged into one. Defaults to 0.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   Diff diffToWorkdir({
     Set<GitDiff> flags = const {GitDiff.normal},
@@ -93,6 +103,16 @@ class Tree {
   }
 
   /// Creates a diff between a tree and repository index.
+  ///
+  /// [index] is the [Index] object to diff to.
+  ///
+  /// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
+  ///
+  /// [contextLines] is the number of unchanged lines that define the boundary
+  /// of a hunk (and to display before and after). Defaults to 3.
+  ///
+  /// [interhunkLines] is the maximum number of unchanged lines between hunk
+  /// boundaries before the hunks will be merged into one. Defaults to 0.
   Diff diffToIndex({
     required Index index,
     Set<GitDiff> flags = const {GitDiff.normal},
@@ -111,6 +131,16 @@ class Tree {
 
   /// Creates a diff with the difference between two tree objects.
   ///
+  /// [tree] is the [Tree] object to diff to.
+  ///
+  /// [flags] is a combination of [GitDiff] flags. Defaults to [GitDiff.normal].
+  ///
+  /// [contextLines] is the number of unchanged lines that define the boundary
+  /// of a hunk (and to display before and after). Defaults to 3.
+  ///
+  /// [interhunkLines] is the maximum number of unchanged lines between hunk
+  /// boundaries before the hunks will be merged into one. Defaults to 0.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   Diff diffToTree({
     required Tree tree,
@@ -138,19 +168,20 @@ class Tree {
 }
 
 class TreeEntry {
-  /// Initializes a new instance of [TreeEntry] class.
+  /// Initializes a new instance of [TreeEntry] class from provided pointer to
+  /// tree entry object in memory.
   const TreeEntry(this._treeEntryPointer);
 
   /// Pointer to memory address for allocated tree entry object.
   final Pointer<git_tree_entry> _treeEntryPointer;
 
-  /// Returns the [Oid] of the object pointed by the entry.
+  /// [Oid] of the object pointed by the entry.
   Oid get oid => Oid(bindings.entryId(_treeEntryPointer));
 
-  /// Returns the filename of a tree entry.
+  /// Filename of a tree entry.
   String get name => bindings.entryName(_treeEntryPointer);
 
-  /// Returns the UNIX file attributes of a tree entry.
+  /// UNIX file attributes of a tree entry.
   GitFilemode get filemode {
     final modeInt = bindings.entryFilemode(_treeEntryPointer);
     return GitFilemode.values.singleWhere((mode) => modeInt == mode.value);

lib/src/treebuilder.dart

@@ -7,7 +7,7 @@ class TreeBuilder {
   /// Initializes a new instance of [TreeBuilder] class from provided
   /// [repo]sitory and optional [tree] objects.
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   TreeBuilder({required Repository repo, Tree? tree}) {
@@ -20,7 +20,7 @@ class TreeBuilder {
   /// Pointer to memory address for allocated tree builder object.
   late final Pointer<git_treebuilder> _treeBuilderPointer;
 
-  /// Returns the number of entries listed in a tree builder.
+  /// Number of entries listed in a tree builder.
   int get length => bindings.entryCount(_treeBuilderPointer);
 
   /// Writes the contents of the tree builder as a tree object.
@@ -29,11 +29,12 @@ class TreeBuilder {
   /// Clears all the entires in the tree builder.
   void clear() => bindings.clear(_treeBuilderPointer);
 
-  /// Returns an entry from the tree builder from its filename.
+  /// Returns an entry from the tree builder with provided [filename].
   ///
-  /// The returned entry is owned by the tree builder and should not be freed manually.
+  /// **IMPORTANT**: the returned entry is owned by the tree builder and
+  /// should not be freed manually.
   ///
-  /// Throws [ArgumentError] if nothing found for provided filename.
+  /// Throws [ArgumentError] if nothing found for provided [filename].
   TreeEntry operator [](String filename) {
     return TreeEntry(bindings.getByFilename(
       builderPointer: _treeBuilderPointer,
@@ -43,12 +44,18 @@ class TreeBuilder {
 
   /// Adds or updates an entry to the tree builder with the given attributes.
   ///
-  /// If an entry named filename already exists, its attributes will be updated with
+  /// If an entry with [filename] already exists, its attributes will be updated with
   /// the given ones.
   ///
   /// By default the entry that you are inserting will be checked for validity;
   /// that it exists in the object database and is of the correct type.
   ///
+  /// [filename] is the filename of the entry.
+  ///
+  /// [oid] is [Oid] of the entry.
+  ///
+  /// [filemode] is one of the [GitFilemode] folder attributes of the entry.
+  ///
   /// Throws a [LibGit2Error] if error occured.
   void add({
     required String filename,
@@ -63,7 +70,7 @@ class TreeBuilder {
     );
   }
 
-  /// Removes an entry from the tree builder by its filename.
+  /// Removes an entry from the tree builder by its [filename].
   ///
   /// Throws a [LibGit2Error] if error occured.
   void remove(String filename) {

lib/src/worktree.dart

@@ -4,14 +4,18 @@ import 'bindings/libgit2_bindings.dart';
 import 'bindings/worktree.dart' as bindings;
 
 class Worktree {
-  /// Initializes a new instance of [Worktree] class by creating new worktree
+  /// Creates new worktree.
-  /// with provided [Repository] object worktree [name], [path] and optional [ref]
-  /// [Reference] object.
   ///
   /// If [ref] is provided, no new branch will be created but specified [ref] will
   /// be used instead.
   ///
-  /// Should be freed to release allocated memory.
+  /// [repo] is the repository to create working tree for.
+  ///
+  /// [name] is the name of the working tree.
+  ///
+  /// [path] is the path to create working tree at.
+  ///
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Worktree.create({
@@ -28,10 +32,9 @@ class Worktree {
     );
   }
 
-  /// Initializes a new instance of [Worktree] class by looking up existing worktree
+  /// Lookups existing worktree in [repo] with provided [name].
-  /// with provided [Repository] object and worktree [name].
   ///
-  /// Should be freed to release allocated memory.
+  /// **IMPORTANT**: Should be freed to release allocated memory.
   ///
   /// Throws a [LibGit2Error] if error occured.
   Worktree.lookup({required Repository repo, required String name}) {
@@ -46,13 +49,13 @@ class Worktree {
   /// Throws a [LibGit2Error] if error occured.
   static List<String> list(Repository repo) => bindings.list(repo.pointer);
 
-  /// Returns the name of the worktree.
+  /// Name of the worktree.
   String get name => bindings.name(_worktreePointer);
 
-  /// Returns the filesystem path for the worktree.
+  /// Filesystem path for the worktree.
   String get path => bindings.path(_worktreePointer);
 
-  /// Checks if worktree is locked.
+  /// Whether worktree is locked.
   ///
   /// A worktree may be locked if the linked working tree is stored on a portable
   /// device which is not available.
@@ -64,7 +67,7 @@ class Worktree {
   /// Unlocks a locked worktree.
   void unlock() => bindings.unlock(_worktreePointer);
 
-  /// Checks if the worktree prunable.
+  /// Whether worktree is prunable.
   ///
   /// A worktree is not prunable in the following scenarios:
   /// - the worktree is linking to a valid on-disk worktree.
@@ -78,7 +81,7 @@ class Worktree {
   /// Prune the working tree, that is remove the git data structures on disk.
   void prune() => bindings.prune(_worktreePointer);
 
-  /// Checks if worktree is valid.
+  /// Whether worktree is valid.
   ///
   /// A valid worktree requires both the git data structures inside the linked parent
   /// repository and the linked working copy to be present.

test/commit_test.dart

@@ -175,7 +175,7 @@ void main() {
         repo: repo,
         message: message,
         author: author,
-        commiter: commiter,
+        committer: commiter,
         tree: tree,
         parents: [parent1, parent2],
       );

test/index_test.dart

@@ -37,12 +37,12 @@ void main() {
 
     test('returns index entry at provided position', () {
       expect(index[3].path, 'file');
-      expect(index[3].sha, fileSha);
+      expect(index[3].oid.sha, fileSha);
     });
 
     test('returns index entry at provided path', () {
       expect(index['file'].path, 'file');
-      expect(index['file'].sha, fileSha);
+      expect(index['file'].oid.sha, fileSha);
     });
 
     test('throws if provided entry position is out of bounds', () {
@@ -93,13 +93,13 @@ void main() {
         final entry = index['file'];
 
         index.add(entry);
-        expect(index['file'].sha, fileSha);
+        expect(index['file'].oid.sha, fileSha);
         expect(index.length, 4);
       });
 
       test('successfully adds with provided path string', () {
         index.add('file');
-        expect(index['file'].sha, fileSha);
+        expect(index['file'].oid.sha, fileSha);
         expect(index.length, 4);
       });
 
@@ -155,21 +155,21 @@ void main() {
         index.addAll(['file', 'feature_file']);
 
         expect(index.length, 2);
-        expect(index['file'].sha, fileSha);
+        expect(index['file'].oid.sha, fileSha);
-        expect(index['feature_file'].sha, featureFileSha);
+        expect(index['feature_file'].oid.sha, featureFileSha);
 
         index.clear();
         index.addAll(['[f]*']);
 
         expect(index.length, 2);
-        expect(index['file'].sha, fileSha);
+        expect(index['file'].oid.sha, fileSha);
-        expect(index['feature_file'].sha, featureFileSha);
+        expect(index['feature_file'].oid.sha, featureFileSha);
 
         index.clear();
         index.addAll(['feature_f???']);
 
         expect(index.length, 1);
-        expect(index['feature_file'].sha, featureFileSha);
+        expect(index['feature_file'].oid.sha, featureFileSha);
       });
 
       test('throws when trying to addAll in bare repository', () {

test/stash_test.dart

@@ -54,8 +54,7 @@ void main() {
 
       repo.createStash(
         stasher: stasher,
-        includeUntracked: true,
+        flags: {GitStash.includeUntracked, GitStash.includeIgnored},
-        includeIgnored: true,
       );
       expect(repo.status.isEmpty, true);
       expect(swpPath.existsSync(), false);
@@ -72,7 +71,7 @@ void main() {
       final index = repo.index;
       index.add('file');
 
-      repo.createStash(stasher: stasher, keepIndex: true);
+      repo.createStash(stasher: stasher, flags: {GitStash.keepIndex});
       expect(repo.status.isEmpty, false);
       expect(repo.stashes.length, 1);
 
@@ -111,7 +110,7 @@ void main() {
       index.add('stash.this');
       expect(index.find('stash.this'), true);
 
-      repo.createStash(stasher: stasher, includeUntracked: true);
+      repo.createStash(stasher: stasher, flags: {GitStash.includeUntracked});
       expect(repo.status.isEmpty, true);
       expect(index.find('stash.this'), false);
 
@@ -204,7 +203,7 @@ void main() {
       index.add('stash.this');
       expect(index.find('stash.this'), true);
 
-      repo.createStash(stasher: stasher, includeUntracked: true);
+      repo.createStash(stasher: stasher, flags: {GitStash.includeUntracked});
       expect(repo.status.isEmpty, true);
       expect(index.find('stash.this'), false);
 
@@ -252,7 +251,7 @@ void main() {
 
     test('returns string representation of Stash object', () {
       File('${tmpDir.path}/stash.this').writeAsStringSync('stash');
-      repo.createStash(stasher: stasher, includeUntracked: true);
+      repo.createStash(stasher: stasher, flags: {GitStash.includeUntracked});
       expect(repo.stashes[0].toString(), contains('Stash{'));
     });
   });