docs: update docs for bindings and api

lib/src/annotated.dart

@@ -83,6 +83,8 @@ class AnnotatedCommit {
   late final Pointer<git_annotated_commit> _annotatedCommitPointer;
 
   /// Pointer to pointer to memory address for allocated commit object.
+  ///
+  /// Note: For internal use.
   Pointer<git_annotated_commit> get pointer => _annotatedCommitPointer;
 
   /// Commit oid that the given annotated commit refers to.

lib/src/bindings/annotated.dart

@@ -5,7 +5,7 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Creates an annotated commit from the given commit id. The resulting
+/// Creates an annotated commit from the given commit id. The returned
 /// annotated commit must be freed with [annotatedFree].
 ///
 /// An annotated commit contains information about how it was looked up, which
@@ -38,7 +38,8 @@ Pointer<git_annotated_commit> lookup({
   }
 }
 
-/// Creates an annotated commit from the given reference.
+/// Creates an annotated commit from the given reference. The returned
+/// annotated commit must be freed with [annotatedFree].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_annotated_commit> fromRef({
@@ -63,7 +64,8 @@ Pointer<git_annotated_commit> fromRef({
   }
 }
 
-/// Creates an annotated commit from a revision string.
+/// Creates an annotated commit from a revision string. The returned
+/// annotated commit must be freed with [annotatedFree].
 ///
 /// See `man gitrevisions`, or http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions
 /// for information on the syntax accepted.
@@ -93,7 +95,8 @@ Pointer<git_annotated_commit> fromRevSpec({
   }
 }
 
-/// Creates an annotated commit from the given fetch head data.
+/// Creates an annotated commit from the given fetch head data. The returned
+/// annotated commit must be freed with [annotatedFree].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_annotated_commit> fromFetchHead({

lib/src/bindings/blame.dart

@@ -5,7 +5,8 @@ import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/oid.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Get the blame for a single file.
+/// Get the blame for a single file. The returned blame must be freed with
+/// [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_blame> file({
@@ -68,6 +69,8 @@ Pointer<git_blame> file({
 /// Lines that differ between the buffer and the committed version are marked
 /// as having a zero OID for their finalCommitOid.
 ///
+/// The returned blame must be freed with [free].
+///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_blame> buffer({
   required Pointer<git_blame> reference,

lib/src/bindings/blob.dart

@@ -6,7 +6,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Lookup a blob object from a repository.
+/// Lookup a blob object from a repository. The returned blob must be freed
+/// with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_blob> lookup({
@@ -40,10 +41,6 @@ bool isBinary(Pointer<git_blob> blob) {
 }
 
 /// Get a read-only buffer with the raw content of a blob.
-///
-/// A pointer to the raw content of a blob is returned; this pointer is owned
-/// internally by the object and shall not be free'd. The pointer may be
-/// invalidated at a later time.
 String content(Pointer<git_blob> blob) {
   return libgit2.git_blob_rawcontent(blob).cast<Utf8>().toDartString();
 }
@@ -126,8 +123,8 @@ Pointer<git_oid> createFromDisk({
   }
 }
 
-/// Create an in-memory copy of a blob. The copy must be explicitly free'd or
+/// Create an in-memory copy of a blob. The returned copy must be freed with
-/// it will leak.
+/// [free].
 Pointer<git_blob> duplicate(Pointer<git_blob> source) {
   final out = calloc<Pointer<git_blob>>();
   libgit2.git_blob_dup(out, source);

lib/src/bindings/branch.dart

@@ -7,7 +7,8 @@ import 'package:libgit2dart/src/bindings/reference.dart' as reference_bindings;
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Return a list of branches.
+/// Return a list of branches. The returned references must be freed with
+/// [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 List<Pointer<git_reference>> list({
@@ -47,10 +48,10 @@ List<Pointer<git_reference>> list({
   return result;
 }
 
-/// Lookup a branch by its name in a repository.
+/// Lookup a branch by its name in a repository. The returned reference must be
+/// freed with [free].
 ///
-/// The generated reference must be freed by the user. The branch name will be
+/// The branch name will be checked for validity.
-/// checked for validity.
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_reference> lookup({
@@ -79,14 +80,13 @@ Pointer<git_reference> lookup({
   }
 }
 
-/// Create a new branch pointing at a target commit.
+/// Create a new branch pointing at a target commit. The returned reference
+/// must be freed with [free].
 ///
 /// 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.
 ///
-/// The returned reference must be freed by the user.
-///
 /// The branch name will be checked for validity.
 ///
 /// Throws a [LibGit2Error] if error occured.
@@ -121,6 +121,9 @@ Pointer<git_reference> create({
 
 /// Delete an existing branch reference.
 ///
+/// Note that if the deletion succeeds, the reference object will not be valid
+/// anymore, and should be freed immediately with [free].
+///
 /// Throws a [LibGit2Error] if error occured.
 void delete(Pointer<git_reference> branch) {
   final error = libgit2.git_branch_delete(branch);
@@ -134,6 +137,9 @@ void delete(Pointer<git_reference> branch) {
 ///
 /// The new branch name will be checked for validity.
 ///
+/// Note that if the move succeeds, the old reference object will not be valid
+/// anymore, and should be freed immediately with [free].
+///
 /// Throws a [LibGit2Error] if error occured.
 void rename({
   required Pointer<git_reference> branchPointer,
@@ -191,7 +197,8 @@ bool isCheckedOut(Pointer<git_reference> branch) {
 /// Get the 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.
+/// (ie. it lives under "refs/heads/" or "refs/remotes/"), and return the
+/// branch part of it.
 ///
 /// Throws a [LibGit2Error] if error occured.
 String name(Pointer<git_reference> ref) {
@@ -238,7 +245,8 @@ String remoteName({
   }
 }
 
-/// Get the upstream of a branch.
+/// Get the upstream of a branch. The returned reference must be freed with
+/// [free].
 ///
 /// Given a reference, this will return a new reference object corresponding to
 /// its remote tracking branch. The reference must be a local branch.
@@ -262,7 +270,8 @@ Pointer<git_reference> getUpstream(Pointer<git_reference> branch) {
 /// Set a branch's upstream branch.
 ///
 /// This will update the configuration to set the branch named [branchName] as
-/// the upstream of branch. Pass a null name to unset the upstream information.
+/// the upstream of branch. Pass a null [branchName] to unset the upstream
+/// information.
 ///
 /// **Note**: The actual tracking reference must have been already created for
 /// the operation to succeed.

lib/src/bindings/commit.dart

@@ -5,9 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Lookup a commit object from a repository.
+/// Lookup a commit object from a repository. The returned commit must be
-///
+/// freed with [free].
-/// The returned object should be released with `free()` when no longer needed.
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_commit> lookup({
@@ -30,6 +29,9 @@ Pointer<git_commit> lookup({
 
 /// Create new commit in the repository.
 ///
+/// The [message] will not be cleaned up automatically. I.e. excess whitespace
+/// will not be removed and no trailing newline will be added.
+///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_oid> create({
   required Pointer<git_repository> repoPointer,
@@ -195,8 +197,8 @@ Pointer<git_oid> amend({
   }
 }
 
-/// Create an in-memory copy of a commit. The copy must be explicitly free'd or
+/// Create an in-memory copy of a commit. The returned copy must be
-/// it will leak.
+/// freed with [free].
 Pointer<git_commit> duplicate(Pointer<git_commit> source) {
   final out = calloc<Pointer<git_commit>>();
   libgit2.git_commit_dup(out, source);
@@ -211,8 +213,7 @@ Pointer<git_commit> duplicate(Pointer<git_commit> source) {
 /// Get the encoding for the message of a commit, as a string representing a
 /// standard encoding name.
 ///
-/// The encoding may be NULL if the encoding header in the commit is missing;
+/// If the encoding header in the commit is missing UTF-8 is assumed.
-/// in that case UTF-8 is assumed.
 String messageEncoding(Pointer<git_commit> commit) {
   final result = libgit2.git_commit_message_encoding(commit);
   return result == nullptr ? 'utf-8' : result.cast<Utf8>().toDartString();
@@ -313,9 +314,9 @@ Pointer<git_commit> parent({
   }
 }
 
-/// Get the commit object that is the th generation ancestor of the named
+/// Get the commit object that is the nth generation ancestor of the named
-/// commit object, following only the first parents. The returned commit has to
+/// commit object, following only the first parents. The returned commit must
-/// be freed by the caller.
+/// be freed with [free].
 ///
 /// Passing 0 as the generation number returns another instance of the base
 /// commit itself.
@@ -353,6 +354,8 @@ Pointer<git_signature> committer(Pointer<git_commit> commit) {
 }
 
 /// Get the author of a commit.
+///
+/// The returned signature must be freed.
 Pointer<git_signature> author(Pointer<git_commit> commit) {
   return libgit2.git_commit_author(commit);
 }
@@ -363,6 +366,8 @@ Pointer<git_oid> treeOid(Pointer<git_commit> commit) {
 }
 
 /// Get the tree pointed to by a commit.
+///
+/// The returned tree must be freed.
 Pointer<git_tree> tree(Pointer<git_commit> commit) {
   final out = calloc<Pointer<git_tree>>();
   libgit2.git_commit_tree(out, commit);
@@ -392,7 +397,7 @@ void revert({
 /// Reverts the given commit against the given "our" commit, producing an index
 /// that reflects the result of the revert.
 ///
-/// The returned index must be freed explicitly with [free].
+/// The returned index must be freed.
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_index> revertCommit({

lib/src/bindings/config.dart

@@ -7,7 +7,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Create a new config instance containing a single on-disk file
+/// Create a new config instance containing a single on-disk file. The returned
+/// config must be freed with [free].
 Pointer<git_config> open(String path) {
   final out = calloc<Pointer<git_config>>();
   final pathC = path.toNativeUtf8().cast<Int8>();
@@ -18,12 +19,14 @@ Pointer<git_config> open(String path) {
   return out.value;
 }
 
-/// Open the global, XDG and system configuration files
+/// Open the global, XDG and system configuration files.
 ///
 /// Utility wrapper that finds the global, XDG and system configuration
 /// files and opens them into a single prioritized config object that can
 /// be used when accessing default config data outside a repository.
 ///
+/// The returned config must be freed with [free].
+///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_config> openDefault() {
   final out = calloc<Pointer<git_config>>();
@@ -40,14 +43,13 @@ Pointer<git_config> openDefault() {
   }
 }
 
-/// Locate the path to the global configuration file
+/// Locate the path to the global configuration file.
 ///
 /// The user or global configuration file is usually located in
 /// `$HOME/.gitconfig`.
 ///
 /// This method will try to guess the full path to that file, if the file
-/// exists. The returned path may be used on any method call to load
+/// exists. The returned path may be used to load the global configuration file.
-/// the global configuration file.
 ///
 /// This method will not guess the path to the xdg compatible config file
 /// (`.config/git/config`).
@@ -69,9 +71,10 @@ String findGlobal() {
   }
 }
 
-/// Locate the path to the system configuration file
+/// Locate the path to the system configuration file.
 ///
-/// If /etc/gitconfig doesn't exist, it will look for %PROGRAMFILES%\Git\etc\gitconfig
+/// If `/etc/gitconfig` doesn't exist, it will look for
+/// `%PROGRAMFILES%\Git\etc\gitconfig`
 ///
 /// Throws a [LibGit2Error] if error occured.
 String findSystem() {
@@ -90,11 +93,15 @@ String findSystem() {
   }
 }
 
-/// Locate the path to the global xdg compatible configuration file
+/// Locate the path to the global xdg compatible configuration file.
 ///
 /// The xdg compatible configuration file is usually located in
 /// `$HOME/.config/git/config`.
 ///
+/// This method will try to guess the full path to that file, if the file
+/// exists. The returned path may be used to load the xdg compatible
+/// configuration file.
+///
 /// Throws a [LibGit2Error] if error occured.
 String findXdg() {
   final out = calloc<git_buf>();
@@ -112,7 +119,8 @@ String findXdg() {
   }
 }
 
-/// Create a snapshot of the configuration.
+/// Create a snapshot of the configuration. The returned config must be freed
+/// with [free].
 ///
 /// 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
@@ -128,7 +136,8 @@ Pointer<git_config> snapshot(Pointer<git_config> config) {
   return result;
 }
 
-/// Get the config entry of a config variable.
+/// Get the config entry of a config variable. The returned config entry must
+/// be freed with [freeEntry].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_config_entry> getEntry({
@@ -190,7 +199,8 @@ void setString({
   calloc.free(valueC);
 }
 
-/// Iterate over all the config variables.
+/// Iterate over all the config variables. The returned iterator must be freed
+/// with [freeIterator].
 Pointer<git_config_iterator> iterator(Pointer<git_config> cfg) {
   final out = calloc<Pointer<git_config_iterator>>();
   libgit2.git_config_iterator_new(out, cfg);
@@ -220,10 +230,14 @@ void delete({
   }
 }
 
-/// Iterate over the values of a multivar
+/// Iterate over the values of a multivar.
 ///
-/// If regexp is present, then the iterator will only iterate over all
+/// If [regexp] is present, then the iterator will only iterate over all
 /// values which match the pattern.
+///
+/// The regular expression is applied case-sensitively on the normalized form
+/// of the variable name: the section and variable parts are lower-cased. The
+/// subsection is left unchanged.
 List<String> multivarValues({
   required Pointer<git_config> configPointer,
   required String variable,
@@ -265,7 +279,7 @@ List<String> multivarValues({
 /// Set the value of a multivar config variable in the config file with the
 /// highest level (usually the local one).
 ///
-/// The regexp is applied case-sensitively on the value.
+/// The [regexp] is applied case-sensitively on the value.
 void setMultivar({
   required Pointer<git_config> configPointer,
   required String variable,
@@ -286,7 +300,7 @@ void setMultivar({
 /// Deletes one or several values from a multivar in the config file
 /// with the highest level (usually the local one).
 ///
-/// The regexp is applied case-sensitively on the value.
+/// The [regexp] is applied case-sensitively on the value.
 void deleteMultivar({
   required Pointer<git_config> configPointer,
   required String variable,

lib/src/bindings/describe.dart

@@ -5,13 +5,10 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Describe a commit.
+/// Describe a commit. The returned describe result must be freed with [free].
 ///
 /// Perform the describe operation on the given committish object.
 ///
-/// Returned object should be freed with `describeResultFree()` once no longer
-/// needed.
-///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_describe_result> commit({
   required Pointer<git_commit> commitPointer,
@@ -44,7 +41,7 @@ Pointer<git_describe_result> commit({
   }
 }
 
-/// Describe a commit.
+/// Describe a commit. The returned describe result must be freed with [free].
 ///
 /// Perform the describe operation on the current commit and the worktree.
 /// After peforming describe on HEAD, a status is run and the description is
@@ -118,7 +115,7 @@ String format({
 }
 
 /// Free the describe result.
-void describeResultFree(Pointer<git_describe_result> result) {
+void free(Pointer<git_describe_result> result) {
   libgit2.git_describe_result_free(result);
 }
 

lib/src/bindings/diff.dart

@@ -5,7 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Create a diff with the difference between two index objects.
+/// Create a diff with the difference between two index objects. The returned
+/// diff must be freed with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_diff> indexToIndex({
@@ -43,7 +44,8 @@ Pointer<git_diff> indexToIndex({
   }
 }
 
-/// Create a diff between the repository index and the workdir directory.
+/// Create a diff between the repository index and the workdir directory. The
+/// returned diff must be freed with [free].
 Pointer<git_diff> indexToWorkdir({
   required Pointer<git_repository> repoPointer,
   required Pointer<git_index> indexPointer,
@@ -68,7 +70,8 @@ Pointer<git_diff> indexToWorkdir({
   return result;
 }
 
-/// Create a diff between a tree and repository index.
+/// Create a diff between a tree and repository index. The returned diff must
+/// be freed with [free].
 Pointer<git_diff> treeToIndex({
   required Pointer<git_repository> repoPointer,
   required Pointer<git_tree>? treePointer,
@@ -100,7 +103,8 @@ Pointer<git_diff> treeToIndex({
   return result;
 }
 
-/// Create a diff between a tree and the working directory.
+/// Create a diff between a tree and the working directory. The returned
+/// diff must be freed with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_diff> treeToWorkdir({
@@ -137,7 +141,8 @@ Pointer<git_diff> treeToWorkdir({
 }
 
 /// Create a diff between a tree and the working directory using index data to
-/// account for staged deletes, tracked files, etc.
+/// account for staged deletes, tracked files, etc. The returned diff must be
+/// freed with [free].
 ///
 /// This emulates `git diff <tree>` by diffing the tree to the index and the
 /// index to the working directory and blending the results into a single diff
@@ -177,7 +182,8 @@ Pointer<git_diff> treeToWorkdirWithIndex({
   }
 }
 
-/// Create a diff with the difference between two tree objects.
+/// Create a diff with the difference between two tree objects. The returned
+/// diff must be freed with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_diff> treeToTree({
@@ -233,7 +239,8 @@ void merge({
   libgit2.git_diff_merge(ontoPointer, fromPointer);
 }
 
-/// Read the contents of a git patch file into a git diff object.
+/// Read the contents of a git patch file into a git diff object. The returned
+/// diff must be freed with [free].
 ///
 /// The diff object produced is similar to the one that would be produced if
 /// you actually produced it computationally by comparing two trees, however
@@ -334,7 +341,8 @@ String statusChar(int status) {
   return String.fromCharCode(libgit2.git_diff_status_char(status));
 }
 
-/// Accumulate diff statistics for all patches.
+/// Accumulate diff statistics for all patches. The returned diff stats must be
+/// freed with [freeStats].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_diff_stats> stats(Pointer<git_diff> diff) {
@@ -458,7 +466,8 @@ bool apply({
   }
 }
 
-/// Apply a diff to a tree, and return the resulting image as an index.
+/// Apply a diff to a tree, and return the resulting image as an index. The
+/// returned index must be freed.
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_index> applyToTree({
@@ -502,7 +511,7 @@ Pointer<git_index> applyToTree({
 }
 
 /// Free a previously allocated diff stats.
-void statsFree(Pointer<git_diff_stats> stats) =>
+void freeStats(Pointer<git_diff_stats> stats) =>
     libgit2.git_diff_stats_free(stats);
 
 /// Free a previously allocated diff.

lib/src/bindings/index.dart

@@ -10,7 +10,7 @@ import 'package:libgit2dart/src/util.dart';
 /// This index object cannot be read/written to the filesystem, but may be
 /// used to perform in-memory index operations.
 ///
-/// The index must be freed once it's no longer in use.
+/// The returned index must be freed with [free].
 Pointer<git_index> newInMemory() {
   final out = calloc<Pointer<git_index>>();
   libgit2.git_index_new(out);
@@ -51,12 +51,12 @@ String path(Pointer<git_index> index) {
 /// Update the contents of an existing index object in memory by reading from
 /// the hard disk.
 ///
-/// If force is true, this performs a "hard" read that discards in-memory
+/// If [force] is true, 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
+/// If [force] is false, this does a "soft" read that reloads the index data
-/// disk only if it has changed since the last time it was loaded. Purely
+/// 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.
 void read({required Pointer<git_index> indexPointer, required bool force}) {
@@ -214,7 +214,7 @@ void add({
 
 /// Add or update an index entry from a file on disk.
 ///
-/// The file path must be relative to the repository's working folder and must
+/// The file [path] must be relative to the repository's working folder and must
 /// be readable.
 ///
 /// This method will fail in bare index instances.
@@ -282,7 +282,7 @@ void addFromBuffer({
 ///
 /// This method will fail in bare index instances.
 ///
-/// The `pathspec` is a list of file names or shell glob patterns that will be
+/// 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).

lib/src/bindings/mailmap.dart

@@ -5,10 +5,11 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Allocate a new mailmap object.
+/// Allocate a new mailmap object. The returned mailmap must be freed with
+/// [free].
 ///
 /// This object is empty, so you'll have to add a mailmap file before you can
-/// do anything with it. The mailmap must be freed with `free()`.
+/// do anything with it.
 Pointer<git_mailmap> init() {
   final out = calloc<Pointer<git_mailmap>>();
   libgit2.git_mailmap_new(out);
@@ -20,7 +21,8 @@ Pointer<git_mailmap> init() {
   return result;
 }
 
-/// Create a new mailmap instance containing a single mailmap file.
+/// Create a new mailmap instance containing a single mailmap file. The
+/// returned mailmap must be freed with [free].
 Pointer<git_mailmap> fromBuffer(String buffer) {
   final out = calloc<Pointer<git_mailmap>>();
   final bufferC = buffer.toNativeUtf8().cast<Int8>();
@@ -36,7 +38,8 @@ Pointer<git_mailmap> fromBuffer(String buffer) {
 }
 
 /// Create a new mailmap instance from a repository, loading mailmap files based
-/// on the repository's configuration.
+/// on the repository's configuration. The returned mailmap must be freed with
+/// [free].
 ///
 /// Mailmaps are loaded in the following order:
 ///
@@ -89,7 +92,8 @@ List<String> resolve({
   return [realName, realEmail];
 }
 
-/// Resolve a signature to use real names and emails with a mailmap.
+/// Resolve a signature to use real names and emails with a mailmap. The
+/// returned signature must be freed.
 Pointer<git_signature> resolveSignature({
   required Pointer<git_mailmap> mailmapPointer,
   required Pointer<git_signature> signaturePointer,

lib/src/bindings/merge.dart

@@ -119,6 +119,10 @@ List<int> analysis({
 /// directory. Any changes are staged for commit and any conflicts are written
 /// to the index. Callers should inspect the repository's index after this
 /// completes, resolve any conflicts and prepare a commit.
+///
+/// For compatibility with git, the repository is put into a merging state.
+/// Once the commit is done (or if the user wishes to abort), that state should
+/// be cleared by calling relative method.
 void merge({
   required Pointer<git_repository> repoPointer,
   required Pointer<git_annotated_commit> theirHeadPointer,
@@ -248,12 +252,12 @@ String mergeFileFromIndex({
   }
 }
 
-/// Merge two commits, producing a git_index that reflects the result of the
+/// Merge two commits, producing a git index that reflects the result of the
 /// merge. The index may be written as-is to the working directory or checked
 /// out. If the index is to be converted to a tree, the caller should resolve
 /// any conflicts that arose as part of the merge.
 ///
-/// The returned index must be freed explicitly.
+/// The returned index must be freed.
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_index> mergeCommits({
@@ -296,7 +300,7 @@ Pointer<git_index> mergeCommits({
 /// out. If the index is to be converted to a tree, the caller should resolve
 /// any conflicts that arose as part of the merge.
 ///
-/// The returned index must be freed explicitly.
+/// The returned index must be freed.
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_index> mergeTrees({

lib/src/bindings/note.dart

@@ -5,9 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Returns list of notes for repository.
+/// Returns list of notes for repository. The returned notes must be freed with
-///
+/// [free].
-/// Notes must be freed manually by the user.
 ///
 /// Throws a [LibGit2Error] if error occured.
 List<Map<String, Pointer>> list(Pointer<git_repository> repo) {
@@ -49,9 +48,7 @@ List<Map<String, Pointer>> list(Pointer<git_repository> repo) {
   return result;
 }
 
-/// Read the note for an object.
+/// Read the note for an object. The returned note must be freed with [free].
-///
-/// The note must be freed manually by the user.
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_note> lookup({
@@ -80,7 +77,7 @@ Pointer<git_note> lookup({
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_oid> create({
   required Pointer<git_repository> repoPointer,
-  String notesRef = 'refs/notes/commits',
+  required String notesRef,
   required Pointer<git_signature> authorPointer,
   required Pointer<git_signature> committerPointer,
   required Pointer<git_oid> oidPointer,
@@ -118,7 +115,7 @@ Pointer<git_oid> create({
 /// Throws a [LibGit2Error] if error occured.
 void delete({
   required Pointer<git_repository> repoPointer,
-  String notesRef = 'refs/notes/commits',
+  required String notesRef,
   required Pointer<git_signature> authorPointer,
   required Pointer<git_signature> committerPointer,
   required Pointer<git_oid> oidPointer,

lib/src/bindings/object.dart

@@ -8,10 +8,8 @@ import 'package:libgit2dart/src/util.dart';
 /// Get the object type of an object.
 int type(Pointer<git_object> obj) => libgit2.git_object_type(obj);
 
-/// Lookup a reference to one of the objects in a repository.
+/// Lookup a reference to one of the objects in a repository. The returned
-///
+/// reference must be freed with [free].
-/// The generated reference is owned by the repository and should be closed with
-/// the `free()` method instead of free'd manually.
 ///
 /// The 'type' parameter must match the type of the object in the odb; the
 /// method will fail otherwise. The special value 'GIT_OBJECT_ANY' may be

lib/src/bindings/odb.dart

@@ -7,7 +7,8 @@ import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/oid.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Create a new object database with no backends.
+/// Create a new object database with no backends. The returned odb must be
+/// freed with [free].
 ///
 /// Before the ODB can be used for read/writing, a custom database backend must be
 /// manually added.
@@ -110,13 +111,11 @@ List<Oid> objects(Pointer<git_odb> odb) {
   return result;
 }
 
-/// Read an object from the database.
+/// Read an object from the database. The returned object must be freed with
+/// [freeObject].
 ///
 /// This method queries all available ODB backends trying to read the given OID.
 ///
-/// The returned object is reference counted and internally cached, so it
-/// should be closed by the user once it's no longer in use.
-///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_odb_object> read({
   required Pointer<git_odb> odbPointer,
@@ -164,14 +163,6 @@ int objectSize(Pointer<git_odb_object> object) {
   return libgit2.git_odb_object_size(object);
 }
 
-/// Close an ODB object.
-///
-/// This method must always be called once a odb object is no longer needed,
-/// otherwise memory will leak.
-void objectFree(Pointer<git_odb_object> object) {
-  libgit2.git_odb_object_free(object);
-}
-
 /// Write raw data into the object database.
 ///
 /// Throws a [LibGit2Error] if error occured.
@@ -208,3 +199,11 @@ Pointer<git_oid> write({
 
 /// Close an open object database.
 void free(Pointer<git_odb> db) => libgit2.git_odb_free(db);
+
+/// Close an ODB object.
+///
+/// This method must always be called once a odb object is no longer needed,
+/// otherwise memory will leak.
+void freeObject(Pointer<git_odb_object> object) {
+  libgit2.git_odb_object_free(object);
+}

lib/src/bindings/packbuilder.dart

@@ -5,7 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Initialize a new packbuilder.
+/// Initialize a new packbuilder. The returned packbuilder must be freed with
+/// [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_packbuilder> init(Pointer<git_repository> repo) {

lib/src/bindings/patch.dart

@@ -5,10 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Directly generate a patch from the difference between two buffers.
+/// Directly generate a patch from the difference between two buffers. The
-///
+/// returned patch must be freed with [free].
-/// You can use the standard patch accessor functions to read the patch data,
-/// and you must free the patch when done.
 Pointer<git_patch> fromBuffers({
   String? oldBuffer,
   String? oldAsPath,
@@ -55,10 +53,8 @@ Pointer<git_patch> fromBuffers({
   return result;
 }
 
-/// Directly generate a patch from the difference between two blobs.
+/// Directly generate a patch from the difference between two blobs. The
-///
+/// returned patch must be freed with [free].
-/// You can use the standard patch accessor functions to read the patch data,
-/// and you must free the patch when done.
 Pointer<git_patch> fromBlobs({
   required Pointer<git_blob>? oldBlobPointer,
   String? oldAsPath,
@@ -97,9 +93,7 @@ Pointer<git_patch> fromBlobs({
 }
 
 /// Directly generate a patch from the difference between a blob and a buffer.
-///
+/// The returned patch must be freed with [free].
-/// You can use the standard patch accessor functions to read the patch data,
-/// and you must free the patch when done.
 Pointer<git_patch> fromBlobAndBuffer({
   Pointer<git_blob>? oldBlobPointer,
   String? oldAsPath,
@@ -143,11 +137,8 @@ Pointer<git_patch> fromBlobAndBuffer({
   return result;
 }
 
-/// Return a patch for an entry in the diff list.
+/// Return a patch for an entry in the diff list. The returned patch must be
-///
+/// freed with [free].
-/// The newly created patch object contains the text diffs for the delta. You
-/// have to call [free] when you are done with it. You can use the patch object
-/// to loop over all the hunks and lines in the diff of the one delta.
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_patch> fromDiff({

lib/src/bindings/rebase.dart

@@ -7,8 +7,8 @@ import 'package:libgit2dart/src/util.dart';
 
 /// Initializes a rebase operation to rebase the changes in [branchPointer]
 /// relative to [upstreamPointer] onto [ontoPointer] another branch. To begin
-/// the rebase process, call [next]. When you have finished with this object,
+/// the rebase process, call [next]. The returned rebase must be freed with
-/// call [free].
+/// [free].
 ///
 /// [branchPointer] is the terminal commit to rebase, or null to rebase the
 /// current branch.
@@ -53,7 +53,8 @@ Pointer<git_rebase> init({
 }
 
 /// Opens an existing rebase that was previously started by either an
-/// invocation of [init] or by another client.
+/// invocation of [init] or by another client. The returned rebase must be
+/// freed with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_rebase> open(Pointer<git_repository> repo) {

lib/src/bindings/reference.dart

@@ -23,10 +23,10 @@ Pointer<git_oid> target(Pointer<git_reference> ref) =>
 /// This method iteratively peels a symbolic reference until it resolves
 /// to a direct reference to an OID.
 ///
-/// The peeled reference must be freed manually once it's no longer needed.
-///
 /// If a direct reference is passed as an argument, a copy of that reference is
-/// returned. This copy must be manually freed too.
+/// returned.
+///
+/// The returned reference must be freed with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_reference> resolve(Pointer<git_reference> ref) {
@@ -44,9 +44,8 @@ Pointer<git_reference> resolve(Pointer<git_reference> ref) {
   }
 }
 
-/// Lookup a reference by name in a repository.
+/// Lookup a reference by name in a repository. The returned reference must be
-///
+/// freed with [free].
-/// The returned reference must be freed by the user.
 ///
 /// The name will be checked for validity.
 ///
@@ -84,7 +83,8 @@ String shorthand(Pointer<git_reference> ref) {
   return libgit2.git_reference_shorthand(ref).cast<Utf8>().toDartString();
 }
 
-/// Rename an existing reference.
+/// Rename an existing reference. The returned reference must be freed with
+/// [free].
 ///
 /// This method works for both direct and symbolic references.
 ///
@@ -203,7 +203,8 @@ bool isTag(Pointer<git_reference> ref) {
   return libgit2.git_reference_is_tag(ref) == 1 || false;
 }
 
-/// Create a new direct reference.
+/// Create a new direct reference and write it to the disk. The returned
+/// reference must be freed with [free].
 ///
 /// A direct reference (also called an object id reference) refers directly to a
 /// specific object id (a.k.a. OID or SHA) in the repository. The id
@@ -211,9 +212,6 @@ bool isTag(Pointer<git_reference> ref) {
 /// moved). For example, in libgit2 the direct ref "refs/tags/v0.17.0" refers
 /// to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977.
 ///
-/// The direct reference will be created in the repository and written to the
-/// disk. The generated reference object must be freed by the user.
-///
 /// Valid reference names must follow one of two patterns:
 ///
 /// Top-level names must contain only capital letters and underscores, and
@@ -264,16 +262,14 @@ Pointer<git_reference> createDirect({
   }
 }
 
-/// Create a new symbolic reference.
+/// Create a new symbolic reference and write it to the disk. The returned
+/// reference must be freed with [free].
 ///
 /// A symbolic reference is a reference name that refers to another reference
 /// name. If the other name moves, the symbolic name will move, too. As a
 /// simple example, the "HEAD" reference might refer to "refs/heads/master"
 /// while on the "master" branch of a repository.
 ///
-/// The symbolic reference will be created in the repository and written to the
-/// disk. The generated reference object must be freed by the user.
-///
 /// Valid reference names must follow one of two patterns:
 ///
 /// Top-level names must contain only capital letters and underscores, and must
@@ -343,6 +339,7 @@ Pointer<git_repository> owner(Pointer<git_reference> ref) {
 /// reference, otherwise this will fail.
 ///
 /// The new reference will be written to disk, overwriting the given reference.
+/// The returned reference must be freed with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_reference> setTarget({
@@ -376,6 +373,7 @@ Pointer<git_reference> setTarget({
 /// otherwise this will fail.
 ///
 /// The new reference will be written to disk, overwriting the given reference.
+/// The returned reference must be freed with [free].
 ///
 /// The target name will be checked for validity.
 ///
@@ -447,7 +445,8 @@ Pointer<git_object> peel({
   }
 }
 
-/// Create a copy of an existing reference.
+/// Create a copy of an existing reference. The returned reference must be
+/// freed with [free].
 Pointer<git_reference> duplicate(Pointer<git_reference> source) {
   final out = calloc<Pointer<git_reference>>();
   libgit2.git_reference_dup(out, source);

lib/src/bindings/reflog.dart

@@ -5,12 +5,11 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Read the reflog for the given reference.
+/// Read the reflog for the given reference. The returned reflog must be
+/// freed with [free].
 ///
 /// If there is no reflog file for the given reference yet, an empty reflog
 /// object will be returned.
-///
-/// The reflog must be freed manually.
 Pointer<git_reflog> read({
   required Pointer<git_repository> repoPointer,
   required String name,
@@ -29,6 +28,8 @@ Pointer<git_reflog> read({
 
 /// Write an existing in-memory reflog object back to disk using an atomic file
 /// lock.
+///
+/// Throws a [LibGit2Error] if error occured.
 void write(Pointer<git_reflog> reflog) {
   final error = libgit2.git_reflog_write(reflog);
 
@@ -132,7 +133,7 @@ String entryMessage(Pointer<git_reflog_entry> entry) {
   return result == nullptr ? '' : result.cast<Utf8>().toDartString();
 }
 
-/// Get the committer of this entry.
+/// Get the committer of this entry. The returned signature must be freed.
 Pointer<git_signature> entryCommiter(Pointer<git_reflog_entry> entry) {
   return libgit2.git_reflog_entry_committer(entry);
 }

lib/src/bindings/remote.dart

@@ -23,7 +23,8 @@ List<String> list(Pointer<git_repository> repo) {
   return result;
 }
 
-/// Get the information for a particular remote.
+/// Get the information for a particular remote. The returned remote must be
+/// freed with [free].
 ///
 /// The name will be checked for validity.
 ///
@@ -49,7 +50,7 @@ Pointer<git_remote> lookup({
 }
 
 /// Add a remote with the default fetch refspec to the repository's
-/// configuration.
+/// configuration. The returned remote must be freed with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_remote> create({
@@ -76,7 +77,7 @@ Pointer<git_remote> create({
 }
 
 /// Add a remote with the provided fetch refspec to the repository's
-/// configuration.
+/// configuration. The returned remote must be freed with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_remote> createWithFetchSpec({
@@ -551,7 +552,7 @@ void prune({
 /// Free the memory associated with a remote.
 ///
 /// This also disconnects from the remote, if the connection has not been closed
-/// yet (using `disconnect()`).
+/// yet (using [disconnect]).
 void free(Pointer<git_remote> remote) => libgit2.git_remote_free(remote);
 
 /// Initializes git_proxy_options structure.

lib/src/bindings/repository.dart

@@ -9,7 +9,8 @@ import 'package:libgit2dart/src/remote.dart';
 import 'package:libgit2dart/src/repository.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Attempt to open an already-existing repository at [path].
+/// Attempt to open an already-existing repository at [path]. The returned
+/// repository must be freed with [free].
 ///
 /// The [path] can point to either a normal or bare repository.
 ///
@@ -59,7 +60,8 @@ String discover({
   return result;
 }
 
-/// Creates a new Git repository in the given folder.
+/// Creates a new Git repository in the given folder. The returned repository
+/// must be freed with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_repository> init({
@@ -113,7 +115,8 @@ Pointer<git_repository> init({
   }
 }
 
-/// Clone a remote repository.
+/// Clone a remote repository. The returned repository must be freed with
+/// [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_repository> clone({
@@ -247,10 +250,8 @@ bool isEmpty(Pointer<git_repository> repo) {
   }
 }
 
-/// Retrieve and resolve the reference pointed at by HEAD.
+/// Retrieve and resolve the reference pointed at by HEAD. The returned
-///
+/// reference must be freed.
-/// The returned `git_reference` will be owned by caller and must be freed
-/// to release the allocated memory and prevent a leak.
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_reference> head(Pointer<git_repository> repo) {
@@ -339,14 +340,12 @@ Map<String, String> identity(Pointer<git_repository> repo) {
   return identity;
 }
 
-/// Get the configuration file for this repository.
+/// Get the configuration file for this repository. The returned config must be
+/// freed.
 ///
 /// If a configuration file has not been set, the default config set for the
 /// repository will be returned, including global and system configurations (if
 /// they are available).
-///
-/// The configuration file must be freed once it's no longer being used by the
-/// user.
 Pointer<git_config> config(Pointer<git_repository> repo) {
   final out = calloc<Pointer<git_config>>();
   libgit2.git_repository_config(out, repo);
@@ -358,14 +357,12 @@ Pointer<git_config> config(Pointer<git_repository> repo) {
   return result;
 }
 
-/// Get a snapshot of the repository's configuration.
+/// Get a snapshot of the repository's configuration. The returned config must
+/// be freed.
 ///
 /// Convenience function to take a snapshot from the repository's configuration.
 /// The contents of this snapshot will not change, even if the underlying
 /// config files are modified.
-///
-/// The configuration file must be freed once it's no longer being used by the
-/// user.
 Pointer<git_config> configSnapshot(Pointer<git_repository> repo) {
   final out = calloc<Pointer<git_config>>();
   libgit2.git_repository_config_snapshot(out, repo);
@@ -377,12 +374,10 @@ Pointer<git_config> configSnapshot(Pointer<git_repository> repo) {
   return result;
 }
 
-/// Get the Index file for this repository.
+/// Get the Index file for this repository. The returned index must be freed.
 ///
 /// If a custom index has not been set, the default index for the repository
 /// will be returned (the one located in `.git/index`).
-///
-/// The index must be freed once it's no longer being used.
 Pointer<git_index> index(Pointer<git_repository> repo) {
   final out = calloc<Pointer<git_index>>();
   libgit2.git_repository_index(out, repo);
@@ -437,13 +432,11 @@ void removeMessage(Pointer<git_repository> repo) {
   libgit2.git_repository_message_remove(repo);
 }
 
-/// Get the Object Database for this repository.
+/// Get the Object Database for this repository. The returned odb must be freed.
 ///
 /// If a custom ODB has not been set, the default database for the repository
 /// will be returned (the one located in `.git/objects`).
 ///
-/// The ODB must be freed once it's no longer being used.
-///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_odb> odb(Pointer<git_repository> repo) {
   final out = calloc<Pointer<git_odb>>();
@@ -460,14 +453,13 @@ Pointer<git_odb> odb(Pointer<git_repository> repo) {
   }
 }
 
-/// Get the Reference Database Backend for this repository.
+/// Get the Reference Database Backend for this repository. The returned refdb
+/// must be freed.
 ///
 /// If a custom refsdb has not been set, the default database for the repository
 /// will be returned (the one that manipulates loose and packed references in
 /// the `.git` directory).
 ///
-/// The refdb must be freed once it's no longer being used.
-///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_refdb> refdb(Pointer<git_repository> repo) {
   final out = calloc<Pointer<git_refdb>>();

lib/src/bindings/revparse.dart

@@ -34,7 +34,7 @@ Pointer<git_revspec> revParse({
 /// See `man gitrevisions`, or https://git-scm.com/docs/git-rev-parse.html#_specifying_revisions
 /// for information on the syntax accepted.
 ///
-/// The returned object should be released when no longer needed.
+/// The returned object should be freed.
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_object> revParseSingle({
@@ -67,7 +67,7 @@ Pointer<git_object> revParseSingle({
 /// point to an 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.
+/// The returned object and reference should be freed.
 ///
 /// Throws a [LibGit2Error] if error occured.
 List<Pointer> revParseExt({

lib/src/bindings/revwalk.dart

@@ -6,7 +6,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Allocate a new revision walker to iterate through a repo.
+/// Allocate a new revision walker to iterate through a repo. The returned
+/// revision walker must be freed with [free].
 ///
 /// This revision walker uses a custom memory pool and an internal commit cache,
 /// so it is relatively expensive to allocate.
@@ -128,7 +129,8 @@ void pushRange({
   }
 }
 
-/// Get the list of commits from the revision walk.
+/// Get the list of commits from the revision walk. The returned commits must
+/// be freed.
 ///
 /// The initial call to this method is not blocking when iterating through a
 /// repo with a time-sorting mode.

lib/src/bindings/signature.dart

@@ -5,7 +5,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Create a new action signature.
+/// Create a new action signature. The returned signature must be freed with
+/// [free].
 ///
 /// Note: angle brackets ('<' and '>') characters are not allowed to be used in
 /// either the name or the email parameter.
@@ -35,7 +36,8 @@ Pointer<git_signature> create({
   }
 }
 
-/// Create a new action signature with a timestamp of 'now'.
+/// Create a new action signature with a timestamp of 'now'. The returned
+/// signature must be freed with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_signature> now({required String name, required String email}) {
@@ -57,7 +59,8 @@ Pointer<git_signature> now({required String name, required String email}) {
   }
 }
 
-/// Create a new action signature with default user and now timestamp.
+/// Create a new action signature with default user and now timestamp. The
+/// returned signature must be freed with [free].
 ///
 /// This looks up the user.name and user.email from the configuration and uses
 /// the current time as the timestamp, and creates a new signature based on
@@ -73,7 +76,8 @@ Pointer<git_signature> defaultSignature(Pointer<git_repository> repo) {
   return result;
 }
 
-/// Create a copy of an existing signature.
+/// Create a copy of an existing signature. The returned signature must be
+/// freed with [free].
 Pointer<git_signature> duplicate(Pointer<git_signature> sig) {
   final out = calloc<Pointer<git_signature>>();
   libgit2.git_signature_dup(out, sig);

lib/src/bindings/status.dart

@@ -6,7 +6,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Gather file status information and populate the git_status_list.
+/// Gather file status information and populate the git_status_list. The
+/// returned list must be freed with [listFree].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_status_list> listNew(Pointer<git_repository> repo) {

lib/src/bindings/submodule.dart

@@ -38,13 +38,12 @@ List<String> list(Pointer<git_repository> repo) {
   return result;
 }
 
-/// Lookup submodule information by name or path.
+/// Lookup submodule information by name or path. The returned submodule must
+/// be freed with [free].
 ///
 /// Given either the submodule name or path (they are usually the same), this
 /// returns a structure describing the submodule.
 ///
-/// You must call [free] when done with the submodule.
-///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_submodule> lookup({
   required Pointer<git_repository> repoPointer,
@@ -67,7 +66,7 @@ Pointer<git_submodule> lookup({
   }
 }
 
-/// Copy submodule info into ".git/config" file.
+/// Copy submodule info into `.git/config` file.
 ///
 /// Just like `git submodule init`, this copies information about the
 /// submodule into `.git/config`.
@@ -143,7 +142,8 @@ Pointer<git_repository> open(Pointer<git_submodule> submodule) {
   }
 }
 
-/// Set up a new git submodule for checkout.
+/// Set up a new git submodule for checkout. The returned submodule must be
+/// freed with [free].
 ///
 /// This does `git submodule add` up to the fetch and checkout of the submodule
 /// contents. It preps a new submodule, creates an entry in `.gitmodules` and

lib/src/bindings/tag.dart

@@ -26,7 +26,8 @@ List<String> list(Pointer<git_repository> repo) {
   }
 }
 
-/// Lookup a tag object from the repository.
+/// Lookup a tag object from the repository. The returned tag must be freed
+/// with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_tag> lookup({
@@ -88,7 +89,7 @@ String message(Pointer<git_tag> tag) {
   return result == nullptr ? '' : result.cast<Utf8>().toDartString();
 }
 
-/// Get the tagger (author) of a tag.
+/// Get the tagger (author) of a tag. The returned signature must be freed.
 Pointer<git_signature> tagger(Pointer<git_tag> tag) =>
     libgit2.git_tag_tagger(tag);
 

lib/src/bindings/tree.dart

@@ -8,7 +8,8 @@ import 'package:libgit2dart/src/util.dart';
 /// Get the id of a tree.
 Pointer<git_oid> id(Pointer<git_tree> tree) => libgit2.git_tree_id(tree);
 
-/// Lookup a tree object from the repository.
+/// Lookup a tree object from the repository. The returned tree must be freed
+/// with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_tree> lookup({
@@ -74,7 +75,7 @@ Pointer<git_tree_entry> getByName({
 /// its relative path.
 ///
 /// Unlike the other lookup functions, the returned tree entry is owned by the
-/// user and must be freed explicitly with [entryFree].
+/// user and must be freed explicitly with [freeEntry].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_tree_entry> getByPath({
@@ -116,7 +117,7 @@ int entryFilemode(Pointer<git_tree_entry> entry) =>
 ///
 /// IMPORTANT: This function is only needed for tree entries owned by the user,
 /// such as [getByPath].
-void entryFree(Pointer<git_tree_entry> entry) =>
+void freeEntry(Pointer<git_tree_entry> entry) =>
     libgit2.git_tree_entry_free(entry);
 
 /// Close an open tree to release memory.

lib/src/bindings/treebuilder.dart

@@ -5,17 +5,12 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Create a new tree builder.
+/// Create a new tree builder. The returned tree builder must be freed with
+/// [free].
 ///
 /// The tree builder can be used to create or modify trees in memory and write
 /// them as tree objects to the database.
 ///
-/// If the source parameter is not null, the tree builder will be initialized
-/// with the entries of the given tree.
-///
-/// If the source parameter is null, the tree builder will start with no entries
-/// and will have to be filled manually.
-///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_treebuilder> create({
   required Pointer<git_repository> repoPointer,

lib/src/bindings/worktree.dart

@@ -6,7 +6,7 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 import 'package:libgit2dart/src/error.dart';
 import 'package:libgit2dart/src/util.dart';
 
-/// Add a new working tree.
+/// Add a new working tree. The returned worktree must be freed with [free].
 ///
 /// Add a new working tree for the repository, that is create the required
 /// data structures inside the repository and check out the current HEAD at
@@ -47,7 +47,8 @@ Pointer<git_worktree> create({
   }
 }
 
-/// Lookup a working tree by its name for a given repository.
+/// Lookup a working tree by its name for a given repository. The returned
+/// worktree must be freed with [free].
 ///
 /// Throws a [LibGit2Error] if error occured.
 Pointer<git_worktree> lookup({

lib/src/blob.dart

@@ -7,6 +7,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 class Blob {
   /// Initializes a new instance of [Blob] class from provided pointer to
   /// blob object in memory.
+  ///
+  /// Note: For internal use. Use [Blob.lookup] instead.
   Blob(this._blobPointer) {
     _finalizer.attach(this, _blobPointer, detach: this);
   }
@@ -23,6 +25,8 @@ class Blob {
   late final Pointer<git_blob> _blobPointer;
 
   /// Pointer to memory address for allocated blob object.
+  ///
+  /// Note: For internal use.
   Pointer<git_blob> get pointer => _blobPointer;
 
   /// Creates a new blob from a [content] string and writes it to ODB.

lib/src/branch.dart

@@ -8,6 +8,10 @@ import 'package:libgit2dart/src/bindings/reference.dart' as reference_bindings;
 class Branch {
   /// Initializes a new instance of [Branch] class from provided pointer to
   /// branch object in memory.
+  ///
+  /// Note: For internal use. Instead, use one of:
+  /// - [Branch.create]
+  /// - [Branch.lookup]
   Branch(this._branchPointer) {
     _finalizer.attach(this, _branchPointer, detach: this);
   }
@@ -65,6 +69,8 @@ class Branch {
   late final Pointer<git_reference> _branchPointer;
 
   /// Pointer to memory address for allocated branch object.
+  ///
+  /// Note: For internal use.
   Pointer<git_reference> get pointer => _branchPointer;
 
   /// Returns a list of branches that can be found in a [repo]sitory for

lib/src/commit.dart

@@ -8,6 +8,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 class Commit {
   /// Initializes a new instance of [Commit] class from provided pointer to
   /// commit object in memory.
+  ///
+  /// Note: For internal use. Use [Commit.lookup] instead.
   Commit(this._commitPointer) {
     _finalizer.attach(this, _commitPointer, detach: this);
   }
@@ -24,6 +26,8 @@ class Commit {
   late final Pointer<git_commit> _commitPointer;
 
   /// Pointer to memory address for allocated commit object.
+  ///
+  /// Note: For internal use.
   Pointer<git_commit> get pointer => _commitPointer;
 
   /// Creates new commit in the [repo]sitory.
@@ -45,7 +49,9 @@ class 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.
+  /// [message] is the full message for this commit. It will not be cleaned up
+  /// automatically. I.e. excess whitespace will not be removed and no trailing
+  /// newline will be added.
   ///
   /// [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].
@@ -208,8 +214,10 @@ class Commit {
     );
   }
 
-  /// Wncoding for the message of a commit, as a string representing a standard
+  /// Encoding for the message of a commit, as a string representing a standard
   /// encoding name.
+  ///
+  /// If the encoding header in the commit is missing UTF-8 is assumed.
   String get messageEncoding => bindings.messageEncoding(_commitPointer);
 
   /// Full message of a commit.

lib/src/config.dart

@@ -11,6 +11,12 @@ import 'package:libgit2dart/src/util.dart';
 class Config with IterableMixin<ConfigEntry> {
   /// Initializes a new instance of [Config] class from provided
   /// pointer to config object in memory.
+  ///
+  /// Note: For internal use. Instead, use one of:
+  /// - [Config.open]
+  /// - [Config.system]
+  /// - [Config.global]
+  /// - [Config.xdg]
   Config(this._configPointer) {
     _finalizer.attach(this, _configPointer, detach: this);
   }
@@ -145,6 +151,10 @@ class Config with IterableMixin<ConfigEntry> {
   ///
   /// If [regexp] is present, then the iterator will only iterate over all
   /// values which match the pattern.
+  ///
+  /// The regular expression is applied case-sensitively on the normalized form
+  /// of the variable name: the section and variable parts are lower-cased. The
+  /// subsection is left unchanged.
   List<String> multivar({required String variable, String? regexp}) {
     return bindings.multivarValues(
       configPointer: _configPointer,

lib/src/diff.dart

@@ -9,6 +9,15 @@ import 'package:libgit2dart/src/util.dart';
 class Diff {
   /// Initializes a new instance of [Diff] class from provided
   /// pointer to diff object in memory.
+  ///
+  /// Note: For internal use. Instead, use one of:
+  /// - [Diff.indexToWorkdir]
+  /// - [Diff.indexToIndex]
+  /// - [Diff.treeToIndex]
+  /// - [Diff.treeToWorkdir]
+  /// - [Diff.treeToWorkdirWithIndex]
+  /// - [Diff.treeToTree]
+  /// - [Diff.parse]
   Diff(this._diffPointer) {
     _finalizer.attach(this, _diffPointer, detach: this);
   }
@@ -262,6 +271,8 @@ class Diff {
   late final Pointer<git_diff> _diffPointer;
 
   /// Pointer to memory address for allocated diff object.
+  ///
+  /// Note: For internal use.
   Pointer<git_diff> get pointer => _diffPointer;
 
   /// How many diff records are there in a diff.
@@ -554,6 +565,8 @@ class DiffFile {
 class DiffStats {
   /// Initializes a new instance of [DiffStats] class from provided
   /// pointer to diff stats object in memory.
+  ///
+  /// Note: For internal use.
   DiffStats(this._diffStatsPointer) {
     _statsFinalizer.attach(this, _diffStatsPointer, detach: this);
   }
@@ -585,7 +598,7 @@ class DiffStats {
 
   /// Releases memory allocated for diff stats object.
   void free() {
-    bindings.statsFree(_diffStatsPointer);
+    bindings.freeStats(_diffStatsPointer);
     _statsFinalizer.detach(this);
   }
 
@@ -598,6 +611,6 @@ class DiffStats {
 
 // coverage:ignore-start
 final _statsFinalizer = Finalizer<Pointer<git_diff_stats>>(
-  (pointer) => bindings.statsFree(pointer),
+  (pointer) => bindings.freeStats(pointer),
 );
 // coverage:ignore-end

lib/src/index.dart

@@ -9,6 +9,8 @@ import 'package:libgit2dart/src/bindings/libgit2_bindings.dart';
 class Index with IterableMixin<IndexEntry> {
   /// Initializes a new instance of [Index] class from provided
   /// pointer to index object in memory.
+  ///
+  /// Note: For internal use.
   Index(this._indexPointer) {
     _finalizer.attach(this, _indexPointer, detach: this);
   }
@@ -25,6 +27,8 @@ class Index with IterableMixin<IndexEntry> {
   late final Pointer<git_index> _indexPointer;
 
   /// Pointer to memory address for allocated index object.
+  ///
+  /// Note: For internal use.
   Pointer<git_index> get pointer => _indexPointer;
 
   /// Full path to the index file on disk.
@@ -321,11 +325,15 @@ final _finalizer = Finalizer<Pointer<git_index>>(
 
 class IndexEntry {
   /// Initializes a new instance of [IndexEntry] class.
+  ///
+  /// Note: For internal use.
   const IndexEntry(this._indexEntryPointer);
 
   final Pointer<git_index_entry> _indexEntryPointer;
 
   /// Pointer to memory address for allocated index entry object.
+  ///
+  /// Note: For internal use.
   Pointer<git_index_entry> get pointer => _indexEntryPointer;
 
   /// [Oid] of the index entry.
@@ -363,6 +371,8 @@ class IndexEntry {
 
 class ConflictEntry {
   /// Initializes a new instance of [ConflictEntry] class.
+  ///
+  /// Note: For internal use.
   const ConflictEntry(
     this._indexPointer,
     this._path,

lib/src/merge.dart

@@ -82,6 +82,10 @@ class Merge {
   /// are written to the index. Callers should inspect the repository's index
   /// after this completes, resolve any conflicts and prepare a commit.
   ///
+  /// For compatibility with git, the repository is put into a merging state.
+  /// Once the commit is done (or if the user wishes to abort), that state
+  /// should be cleared by calling [stateCleanup] method of [Repository] object.
+  ///
   /// [repo] is the repository to merge.
   ///
   /// [commit] is the commit to merge.

lib/src/note.dart

@@ -6,6 +6,8 @@ import 'package:libgit2dart/src/bindings/note.dart' as bindings;
 class Note {
   /// Initializes a new instance of the [Note] class from provided
   /// pointer to note and annotatedOid objects in memory.
+  ///
+  /// Note: For internal use. Use [Note.lookup] instead.
   Note(this._notePointer, this._annotatedOidPointer) {
     _finalizer.attach(this, _notePointer, detach: this);
   }
@@ -100,6 +102,7 @@ class Note {
   }) {
     bindings.delete(
       repoPointer: repo.pointer,
+      notesRef: notesRef,
       authorPointer: author.pointer,
       committerPointer: committer.pointer,
       oidPointer: annotatedOid.pointer,

lib/src/odb.dart

@@ -7,6 +7,8 @@ import 'package:libgit2dart/src/util.dart';
 class Odb {
   /// Initializes a new instance of [Odb] class from provided
   /// pointer to Odb object in memory.
+  ///
+  /// Note: For internal use.
   Odb(this._odbPointer) {
     _finalizer.attach(this, _odbPointer, detach: this);
   }
@@ -25,6 +27,8 @@ class Odb {
   late final Pointer<git_odb> _odbPointer;
 
   /// Pointer to memory address for allocated oid object.
+  ///
+  /// Note: For internal use.
   Pointer<git_odb> get pointer => _odbPointer;
 
   /// Adds an on-disk alternate to an existing Object DB.
@@ -132,7 +136,7 @@ class OdbObject {
 
   /// Releases memory allocated for odbObject object.
   void free() {
-    bindings.objectFree(_odbObjectPointer);
+    bindings.freeObject(_odbObjectPointer);
     _objectfinalizer.detach(this);
   }
 
@@ -144,6 +148,6 @@ class OdbObject {
 
 // coverage:ignore-start
 final _objectfinalizer = Finalizer<Pointer<git_odb_object>>(
-  (pointer) => bindings.objectFree(pointer),
+  (pointer) => bindings.freeObject(pointer),
 );
 // coverage:ignore-end

lib/src/oid.dart

@@ -11,6 +11,8 @@ import 'package:meta/meta.dart';
 class Oid {
   /// Initializes a new instance of [Oid] class from provided
   /// pointer to Oid object in memory.
+  ///
+  /// Note: For internal use. Use [Oid.fromSHA] instead.
   Oid(this._oidPointer);
 
   /// Initializes a new instance of [Oid] class by determining if an object can
@@ -45,6 +47,8 @@ class Oid {
   late final Pointer<git_oid> _oidPointer;
 
   /// Pointer to memory address for allocated oid object.
+  ///
+  /// Note: For internal use.
   Pointer<git_oid> get pointer => _oidPointer;
 
   /// Hexadecimal SHA string.

lib/src/packbuilder.dart

@@ -7,6 +7,8 @@ class PackBuilder {
   /// Initializes a new instance of [PackBuilder] class.
   ///
   /// Throws a [LibGit2Error] if error occured.
+  ///
+  /// Note: For internal use.
   PackBuilder(Repository repo) {
     _packbuilderPointer = bindings.init(repo.pointer);
     _finalizer.attach(this, _packbuilderPointer, detach: this);

lib/src/patch.dart

@@ -9,6 +9,12 @@ import 'package:libgit2dart/src/util.dart';
 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.
+  ///
+  /// Note: For internal use. Instead, use one of:
+  /// - [Patch.fromBlobs]
+  /// - [Patch.fromBlobAndBuffer]
+  /// - [Patch.fromBuffers]
+  /// - [Patch.fromDiff]
   Patch(this._patchPointer) {
     _finalizer.attach(this, _patchPointer, detach: this);
   }
@@ -151,6 +157,8 @@ class Patch {
   late final Pointer<git_patch> _patchPointer;
 
   /// Line counts of each type in a patch.
+  ///
+  /// This helps imitate a `diff --numstat` type of output.
   PatchStats get stats {
     final result = bindings.lineStats(_patchPointer);
 

lib/src/reference.dart

@@ -10,6 +10,10 @@ import 'package:libgit2dart/src/bindings/repository.dart'
 
 class Reference {
   /// Initializes a new instance of the [Reference] class.
+  ///
+  /// Note: For internal use. Instead, use one of:
+  /// - [Reference.create]
+  /// - [Reference.lookup]
   Reference(this._refPointer) {
     _finalizer.attach(this, _refPointer, detach: this);
   }
@@ -78,6 +82,8 @@ class Reference {
   late Pointer<git_reference> _refPointer;
 
   /// Pointer to memory address for allocated reference object.
+  ///
+  /// Note: For internal use.
   Pointer<git_reference> get pointer => _refPointer;
 
   /// Deletes an existing reference with provided [name].

lib/src/reflog.dart

@@ -85,6 +85,8 @@ class RefLog with IterableMixin<RefLogEntry> {
 
   /// Writes an existing in-memory reflog object back to disk using an atomic
   /// file lock.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
   void write() => bindings.write(_reflogPointer);
 
   /// Releases memory allocated for reflog object.

lib/src/refspec.dart

@@ -6,6 +6,8 @@ import 'package:libgit2dart/src/bindings/refspec.dart' as bindings;
 class Refspec {
   /// Initializes a new instance of the [Refspec] class
   /// from provided pointer to refspec object in memory.
+  ///
+  /// Note: For internal use.
   const Refspec(this._refspecPointer);
 
   /// Pointer to memory address for allocated refspec object.

lib/src/remote.dart

@@ -317,6 +317,8 @@ final _finalizer = Finalizer<Pointer<git_remote>>(
 class TransferProgress {
   /// Initializes a new instance of [TransferProgress] class from provided
   /// pointer to transfer progress object in memory.
+  ///
+  /// Note: For internal use.
   const TransferProgress(this._transferProgressPointer);
 
   /// Pointer to memory address for allocated transfer progress object.

lib/src/repository.dart

@@ -18,6 +18,11 @@ class Repository {
   /// pointer to repository object in memory.
   ///
   /// **IMPORTANT**: Should be freed to release allocated memory.
+  ///
+  /// Note: For internal use. Instead, use one of:
+  /// - [Repository.init]
+  /// - [Repository.open]
+  /// - [Repository.clone]
   Repository(this._repoPointer);
 
   /// Creates new git repository at the provided [path].
@@ -151,6 +156,8 @@ class Repository {
   late final Pointer<git_repository> _repoPointer;
 
   /// Pointer to memory address for allocated repository object.
+  ///
+  /// Note: For internal use.
   Pointer<git_repository> get pointer => _repoPointer;
 
   /// Looks for a git repository and return its path. The lookup start from
@@ -686,7 +693,7 @@ class Repository {
       dirtySuffix: dirtySuffix,
     );
 
-    describe_bindings.describeResultFree(describeResult);
+    describe_bindings.free(describeResult);
 
     return result;
   }

lib/src/revwalk.dart

@@ -13,6 +13,8 @@ class RevWalk {
   late final Pointer<git_revwalk> _revWalkPointer;
 
   /// Pointer to memory address for allocated [RevWalk] object.
+  ///
+  /// Note: For internal use.
   Pointer<git_revwalk> get pointer => _revWalkPointer;
 
   /// Returns the list of commits from the revision walk.

lib/src/signature.dart

@@ -10,6 +10,10 @@ import 'package:meta/meta.dart';
 class Signature {
   /// Initializes a new instance of [Signature] class from provided pointer to
   /// signature object in memory.
+  ///
+  /// Note: For internal use. Instead, use one of:
+  /// - [Signature.create]
+  /// - [Signature.defaultSignature]
   Signature(Pointer<git_signature> pointer) {
     _signaturePointer = bindings.duplicate(pointer);
     _finalizer.attach(this, _signaturePointer, detach: this);
@@ -54,6 +58,8 @@ class Signature {
   late final Pointer<git_signature> _signaturePointer;
 
   /// Pointer to memory address for allocated signature object.
+  ///
+  /// Note: For internal use.
   Pointer<git_signature> get pointer => _signaturePointer;
 
   /// Full name of the author.

lib/src/tag.dart

@@ -8,6 +8,8 @@ import 'package:libgit2dart/src/bindings/tag.dart' as bindings;
 class Tag {
   /// Initializes a new instance of [Tag] class from provided pointer to
   /// tag object in memory.
+  ///
+  /// Note: For internal use. Use [Tag.lookup] instead.
   Tag(this._tagPointer) {
     _finalizer.attach(this, _tagPointer, detach: this);
   }

lib/src/tree.dart

@@ -7,6 +7,8 @@ import 'package:libgit2dart/src/bindings/tree.dart' as bindings;
 class Tree {
   /// Initializes a new instance of [Tree] class from provided pointer to
   /// tree object in memory.
+  ///
+  /// Note: For internal use. Use [Tree.lookup] instead.
   Tree(this._treePointer) {
     _finalizer.attach(this, _treePointer, detach: this);
   }
@@ -23,6 +25,8 @@ class Tree {
   late final Pointer<git_tree> _treePointer;
 
   /// Pointer to memory address for allocated tree object.
+  ///
+  /// Note: For internal use.
   Pointer<git_tree> get pointer => _treePointer;
 
   /// List with tree entries of a tree.
@@ -109,6 +113,8 @@ final _finalizer = Finalizer<Pointer<git_tree>>(
 class TreeEntry {
   /// Initializes a new instance of [TreeEntry] class from provided pointer to
   /// tree entry object in memory.
+  ///
+  /// Note: For internal use.
   TreeEntry(this._treeEntryPointer);
 
   /// Initializes a new instance of [TreeEntry] class from provided pointer to
@@ -138,7 +144,7 @@ class TreeEntry {
   ///
   /// **IMPORTANT**: Only tree entries looked up by path should be freed.
   void free() {
-    bindings.entryFree(_treeEntryPointer);
+    bindings.freeEntry(_treeEntryPointer);
     _entryFinalizer.detach(this);
   }
 
@@ -148,6 +154,6 @@ class TreeEntry {
 
 // coverage:ignore-start
 final _entryFinalizer = Finalizer<Pointer<git_tree_entry>>(
-  (pointer) => bindings.entryFree(pointer),
+  (pointer) => bindings.freeEntry(pointer),
 );
 // coverage:ignore-end