rugged 0.28.4.1 → 1.0.1

data/vendor/libgit2/include/git2/stash.h

@@ -120,14 +120,14 @@ typedef int GIT_CALLBACK(git_stash_apply_progress_cb)(
  * Stash application options structure
  *
  * Initialize with `GIT_STASH_APPLY_OPTIONS_INIT`. Alternatively, you can
- * use `git_stash_apply_init_options`.
+ * use `git_stash_apply_options_init`.
  *
  */
 typedef struct git_stash_apply_options {
 	unsigned int version;
 
-	/** See `git_stash_apply_flags_t`, above. */
-	git_stash_apply_flags flags;
+	/** See `git_stash_apply_flags`, above. */
+	uint32_t flags;
 
 	/** Options to use when writing files to the working directory. */
 	git_checkout_options checkout_options;
@@ -153,7 +153,7 @@ typedef struct git_stash_apply_options {
  * @param version The struct version; pass `GIT_STASH_APPLY_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_stash_apply_init_options(
+GIT_EXTERN(int) git_stash_apply_options_init(
 	git_stash_apply_options *opts, unsigned int version);
 
 /**

data/vendor/libgit2/include/git2/status.h

@@ -163,27 +163,36 @@ typedef enum {
 /**
  * Options to control how `git_status_foreach_ext()` will issue callbacks.
  *
- * This structure is set so that zeroing it out will give you relatively
- * sane defaults.
+ * Initialize with `GIT_STATUS_OPTIONS_INIT`. Alternatively, you can
+ * use `git_status_options_init`.
  *
- * The `show` value is one of the `git_status_show_t` constants that
- * control which files to scan and in what order.
- *
- * The `flags` value is an OR'ed combination of the `git_status_opt_t`
- * values above.
- *
- * The `pathspec` is an array of path patterns to match (using
- * fnmatch-style matching), or just an array of paths to match exactly if
- * `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags.
- *
- * The `baseline` is the tree to be used for comparison to the working directory
- * and index; defaults to HEAD.
  */
 typedef struct {
-	unsigned int      version;
+	unsigned int      version; /**< The version */
+
+	/**
+	 * The `show` value is one of the `git_status_show_t` constants that
+	 * control which files to scan and in what order.
+	 */
 	git_status_show_t show;
+
+	/**
+	 * The `flags` value is an OR'ed combination of the `git_status_opt_t`
+	 * values above.
+	 */
 	unsigned int      flags;
+
+	/**
+	 * The `pathspec` is an array of path patterns to match (using
+	 * fnmatch-style matching), or just an array of paths to match exactly if
+	 * `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags.
+	 */
 	git_strarray      pathspec;
+
+	/**
+	 * The `baseline` is the tree to be used for comparison to the working directory
+	 * and index; defaults to HEAD.
+	 */
 	git_tree          *baseline;
 } git_status_options;
 
@@ -200,7 +209,7 @@ typedef struct {
  * @param version The struct version; pass `GIT_STATUS_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_status_init_options(
+GIT_EXTERN(int) git_status_options_init(
 	git_status_options *opts,
 	unsigned int version);
 

data/vendor/libgit2/include/git2/submodule.h

@@ -122,7 +122,7 @@ typedef int GIT_CALLBACK(git_submodule_cb)(
  * Submodule update options structure
  *
  * Initialize with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. Alternatively, you can
- * use `git_submodule_update_init_options`.
+ * use `git_submodule_update_options_init`.
  *
  */
 typedef struct git_submodule_update_options {
@@ -168,7 +168,7 @@ typedef struct git_submodule_update_options {
  * @param version The struct version; pass `GIT_SUBMODULE_UPDATE_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_submodule_update_init_options(
+GIT_EXTERN(int) git_submodule_update_options_init(
 	git_submodule_update_options *opts, unsigned int version);
 
 /**
@@ -263,7 +263,8 @@ GIT_EXTERN(int) git_submodule_foreach(
  * from the working directory to the new repo.
  *
  * To fully emulate "git submodule add" call this function, then open the
- * submodule repo and perform the clone step as needed.  Lastly, call
+ * submodule repo and perform the clone step as needed (if you don't need
+ * anything custom see `git_submodule_add_clone()`). Lastly, call
  * `git_submodule_add_finalize()` to wrap up adding the new submodule and
  * .gitmodules to the index to be ready to commit.
  *
@@ -285,6 +286,22 @@ GIT_EXTERN(int) git_submodule_add_setup(
 	const char *path,
 	int use_gitlink);
 
+/**
+ * Perform the clone step for a newly created submodule.
+ *
+ * This performs the necessary `git_clone` to setup a newly-created submodule.
+ *
+ * @param out The newly created repository object. Optional.
+ * @param submodule The submodule currently waiting for its clone.
+ * @param opts The options to use.
+ *
+ * @return 0 on success, -1 on other errors (see git_clone).
+ */
+GIT_EXTERN(int) git_submodule_clone(
+	git_repository **out,
+	git_submodule *submodule,
+	const git_submodule_update_options *opts);
+
 /**
  * Resolve the setup of a new git submodule.
  *

data/vendor/libgit2/include/git2/sys/alloc.h

@@ -21,51 +21,51 @@ GIT_BEGIN_DECL
  * that all fields need to be set to a proper function.
  */
 typedef struct {
-	/* Allocate `n` bytes of memory */
+	/** Allocate `n` bytes of memory */
 	void * GIT_CALLBACK(gmalloc)(size_t n, const char *file, int line);
 
-	/*
+	/**
 	 * Allocate memory for an array of `nelem` elements, where each element
 	 * has a size of `elsize`. Returned memory shall be initialized to
 	 * all-zeroes
 	 */
 	void * GIT_CALLBACK(gcalloc)(size_t nelem, size_t elsize, const char *file, int line);
 
-	/* Allocate memory for the string `str` and duplicate its contents. */
+	/** Allocate memory for the string `str` and duplicate its contents. */
 	char * GIT_CALLBACK(gstrdup)(const char *str, const char *file, int line);
 
-	/*
+	/**
 	 * Equivalent to the `gstrdup` function, but only duplicating at most
 	 * `n + 1` bytes
 	 */
 	char * GIT_CALLBACK(gstrndup)(const char *str, size_t n, const char *file, int line);
 
-	/*
+	/**
 	 * Equivalent to `gstrndup`, but will always duplicate exactly `n` bytes
 	 * of `str`. Thus, out of bounds reads at `str` may happen.
 	 */
 	char * GIT_CALLBACK(gsubstrdup)(const char *str, size_t n, const char *file, int line);
 
-	/*
+	/**
 	 * This function shall deallocate the old object `ptr` and return a
 	 * pointer to a new object that has the size specified by `size`. In
 	 * case `ptr` is `NULL`, a new array shall be allocated.
 	 */
 	void * GIT_CALLBACK(grealloc)(void *ptr, size_t size, const char *file, int line);
 
-	/*
+	/**
 	 * This function shall be equivalent to `grealloc`, but allocating
 	 * `neleme * elsize` bytes.
 	 */
 	void * GIT_CALLBACK(greallocarray)(void *ptr, size_t nelem, size_t elsize, const char *file, int line);
 
-	/*
+	/**
 	 * This function shall allocate a new array of `nelem` elements, where
 	 * each element has a size of `elsize` bytes.
 	 */
 	void * GIT_CALLBACK(gmallocarray)(size_t nelem, size_t elsize, const char *file, int line);
 
-	/*
+	/**
 	 * This function shall free the memory pointed to by `ptr`. In case
 	 * `ptr` is `NULL`, this shall be a no-op.
 	 */

data/vendor/libgit2/include/git2/sys/cred.h

@@ -0,0 +1,15 @@
+/*
+ * Copyright (C) the libgit2 contributors. All rights reserved.
+ *
+ * This file is part of libgit2, distributed under the GNU GPL v2 with
+ * a Linking Exception. For full terms see the included COPYING file.
+ */
+#ifndef INCLUDE_sys_git_cred_h__
+#define INCLUDE_sys_git_cred_h__
+
+/* These declarations have moved. */
+#ifndef GIT_DEPRECATE_HARD
+# include "git2/sys/credential.h"
+#endif
+
+#endif

data/vendor/libgit2/include/git2/sys/credential.h

@@ -0,0 +1,90 @@
+/*
+ * Copyright (C) the libgit2 contributors. All rights reserved.
+ *
+ * This file is part of libgit2, distributed under the GNU GPL v2 with
+ * a Linking Exception. For full terms see the included COPYING file.
+ */
+#ifndef INCLUDE_sys_git_credential_h__
+#define INCLUDE_sys_git_credential_h__
+
+#include "git2/common.h"
+#include "git2/credential.h"
+
+/**
+ * @file git2/sys/cred.h
+ * @brief Git credentials low-level implementation
+ * @defgroup git_credential Git credentials low-level implementation
+ * @ingroup Git
+ * @{
+ */
+GIT_BEGIN_DECL
+
+/**
+ * The base structure for all credential types
+ */
+struct git_credential {
+	git_credential_t credtype; /**< A type of credential */
+
+	/** The deallocator for this type of credentials */
+	void GIT_CALLBACK(free)(git_credential *cred);
+};
+
+/** A plaintext username and password */
+struct git_credential_userpass_plaintext {
+	git_credential parent; /**< The parent credential */
+	char *username;        /**< The username to authenticate as */
+	char *password;        /**< The password to use */
+};
+
+/** Username-only credential information */
+struct git_credential_username {
+	git_credential parent; /**< The parent credential */
+	char username[1];      /**< The username to authenticate as */
+};
+
+/**
+ * A ssh key from disk
+ */
+struct git_credential_ssh_key {
+	git_credential parent; /**< The parent credential */
+	char *username;        /**< The username to authenticate as */
+	char *publickey;       /**< The path to a public key */
+	char *privatekey;      /**< The path to a private key */
+	char *passphrase;      /**< Passphrase to decrypt the private key */
+};
+
+/**
+ * Keyboard-interactive based ssh authentication
+ */
+struct git_credential_ssh_interactive {
+	git_credential parent; /**< The parent credential */
+	char *username;        /**< The username to authenticate as */
+
+	/**
+	 * Callback used for authentication.
+	 */
+	git_credential_ssh_interactive_cb prompt_callback;
+
+	void *payload;         /**< Payload passed to prompt_callback */
+};
+
+/**
+ * A key with a custom signature function
+ */
+struct git_credential_ssh_custom {
+	git_credential parent; /**< The parent credential */
+	char *username;        /**< The username to authenticate as */
+	char *publickey;       /**< The public key data */
+	size_t publickey_len;  /**< Length of the public key */
+
+	/**
+	 * Callback used to sign the data.
+	 */
+	git_credential_sign_cb sign_callback;
+
+	void *payload;         /**< Payload passed to prompt_callback */
+};
+
+GIT_END_DECL
+
+#endif

data/vendor/libgit2/include/git2/sys/index.h

@@ -75,8 +75,9 @@ GIT_EXTERN(int) git_index_name_add(git_index *index,
  * Remove all filename conflict entries.
  *
  * @param index an existing index object
+ * @return 0 or an error code
  */
-GIT_EXTERN(void) git_index_name_clear(git_index *index);
+GIT_EXTERN(int) git_index_name_clear(git_index *index);
 
 /**@}*/
 
@@ -170,8 +171,9 @@ GIT_EXTERN(int) git_index_reuc_remove(git_index *index, size_t n);
  * Remove all resolve undo entries from the index
  *
  * @param index an existing index object
+ * @return 0 or an error code
  */
-GIT_EXTERN(void) git_index_reuc_clear(git_index *index);
+GIT_EXTERN(int) git_index_reuc_clear(git_index *index);
 
 /**@}*/
 

data/vendor/libgit2/include/git2/sys/mempack.h

@@ -78,8 +78,9 @@ GIT_EXTERN(int) git_mempack_dump(git_buf *pack, git_repository *repo, git_odb_ba
  * semantics to the Git repository.
  *
  * @param backend The mempack backend
+ * @return 0 on success; error code otherwise
  */
-GIT_EXTERN(void) git_mempack_reset(git_odb_backend *backend);
+GIT_EXTERN(int) git_mempack_reset(git_odb_backend *backend);
 
 GIT_END_DECL
 

data/vendor/libgit2/include/git2/sys/merge.h

@@ -41,7 +41,7 @@ GIT_EXTERN(git_merge_driver *) git_merge_driver_lookup(const char *name);
 typedef struct git_merge_driver_source git_merge_driver_source;
 
 /** Get the repository that the source data is coming from. */
-GIT_EXTERN(const git_repository *) git_merge_driver_source_repo(
+GIT_EXTERN(git_repository *) git_merge_driver_source_repo(
 	const git_merge_driver_source *src);
 
 /** Gets the ancestor of the file to merge. */

data/vendor/libgit2/include/git2/sys/odb_backend.h

@@ -30,8 +30,8 @@ struct git_odb_backend {
 
 	/* read and read_prefix each return to libgit2 a buffer which
 	 * will be freed later. The buffer should be allocated using
-	 * the function git_odb_backend_malloc to ensure that it can
-	 * be safely freed later. */
+	 * the function git_odb_backend_data_alloc to ensure that libgit2
+	 * can safely free it later. */
 	int GIT_CALLBACK(read)(
 		void **, size_t *, git_object_t *, git_odb_backend *, const git_oid *);
 
@@ -53,7 +53,7 @@ struct git_odb_backend {
 		git_odb_backend *, const git_oid *, const void *, size_t, git_object_t);
 
 	int GIT_CALLBACK(writestream)(
-		git_odb_stream **, git_odb_backend *, git_off_t, git_object_t);
+		git_odb_stream **, git_odb_backend *, git_object_size_t, git_object_t);
 
 	int GIT_CALLBACK(readstream)(
 		git_odb_stream **, size_t *, git_object_t *,
@@ -82,7 +82,7 @@ struct git_odb_backend {
 
 	int GIT_CALLBACK(writepack)(
 		git_odb_writepack **, git_odb_backend *, git_odb *odb,
-		git_transfer_progress_cb progress_cb, void *progress_payload);
+		git_indexer_progress_cb progress_cb, void *progress_payload);
 
 	/**
 	 * "Freshens" an already existing object, updating its last-used
@@ -117,8 +117,52 @@ GIT_EXTERN(int) git_odb_init_backend(
 	git_odb_backend *backend,
 	unsigned int version);
 
+/**
+ * Allocate data for an ODB object.  Custom ODB backends may use this
+ * to provide data back to the ODB from their read function.  This
+ * memory should not be freed once it is returned to libgit2.  If a
+ * custom ODB uses this function but encounters an error and does not
+ * return this data to libgit2, then they should use the corresponding
+ * git_odb_backend_data_free function.
+ *
+ * @param backend the ODB backend that is allocating this memory
+ * @param len the number of bytes to allocate
+ * @return the allocated buffer on success or NULL if out of memory
+ */
+GIT_EXTERN(void *) git_odb_backend_data_alloc(git_odb_backend *backend, size_t len);
+
+/**
+ * Frees custom allocated ODB data.  This should only be called when
+ * memory allocated using git_odb_backend_data_alloc is not returned
+ * to libgit2 because the backend encountered an error in the read
+ * function after allocation and did not return this data to libgit2.
+ *
+ * @param backend the ODB backend that is freeing this memory
+ * @param data the buffer to free
+ */
+GIT_EXTERN(void) git_odb_backend_data_free(git_odb_backend *backend, void *data);
+
+
+/*
+ * Users can avoid deprecated functions by defining `GIT_DEPRECATE_HARD`.
+ */
+#ifndef GIT_DEPRECATE_HARD
+
+/**
+ * Allocate memory for an ODB object from a custom backend.  This is
+ * an alias of `git_odb_backend_data_alloc` and is preserved for
+ * backward compatibility.
+ *
+ * This function is deprecated, but there is no plan to remove this
+ * function at this time.
+ *
+ * @deprecated git_odb_backend_data_alloc
+ * @see git_odb_backend_data_alloc
+ */
 GIT_EXTERN(void *) git_odb_backend_malloc(git_odb_backend *backend, size_t len);
 
+#endif
+
 GIT_END_DECL
 
 #endif

data/vendor/libgit2/include/git2/sys/refdb_backend.h

@@ -58,11 +58,18 @@ struct git_reference_iterator {
 
 /** An instance for a custom backend */
 struct git_refdb_backend {
-	unsigned int version;
+	unsigned int version; /**< The backend API version */
 
 	/**
-	 * Queries the refdb backend to determine if the given ref_name
-	 * exists.  A refdb implementation must provide this function.
+	 * Queries the refdb backend for the existence of a reference.
+	 *
+	 * A refdb implementation must provide this function.
+	 *
+	 * @arg exists The implementation shall set this to `0` if a ref does
+	 *             not exist, otherwise to `1`.
+	 * @arg ref_name The reference's name that should be checked for
+	 *               existence.
+	 * @return `0` on success, a negative error value code.
 	 */
 	int GIT_CALLBACK(exists)(
 		int *exists,
@@ -70,8 +77,16 @@ struct git_refdb_backend {
 		const char *ref_name);
 
 	/**
-	 * Queries the refdb backend for a given reference.  A refdb
-	 * implementation must provide this function.
+	 * Queries the refdb backend for a given reference.
+	 *
+	 * A refdb implementation must provide this function.
+	 *
+	 * @arg out The implementation shall set this to the allocated
+	 *          reference, if it could be found, otherwise to `NULL`.
+	 * @arg ref_name The reference's name that should be checked for
+	 *               existence.
+	 * @return `0` on success, `GIT_ENOTFOUND` if the reference does
+	 *         exist, otherwise a negative error code.
 	 */
 	int GIT_CALLBACK(lookup)(
 		git_reference **out,
@@ -82,88 +97,216 @@ struct git_refdb_backend {
 	 * Allocate an iterator object for the backend.
 	 *
 	 * A refdb implementation must provide this function.
+	 *
+	 * @arg out The implementation shall set this to the allocated
+	 *          reference iterator. A custom structure may be used with an
+	 *          embedded `git_reference_iterator` structure. Both `next`
+	 *          and `next_name` functions of `git_reference_iterator` need
+	 *          to be populated.
+	 * @arg glob A pattern to filter references by. If given, the iterator
+	 *           shall only return references that match the glob when
+	 *           passed to `wildmatch`.
+	 * @return `0` on success, otherwise a negative error code.
 	 */
 	int GIT_CALLBACK(iterator)(
 		git_reference_iterator **iter,
 		struct git_refdb_backend *backend,
 		const char *glob);
 
-	/*
-	 * Writes the given reference to the refdb.  A refdb implementation
-	 * must provide this function.
+	/**
+	 * Writes the given reference to the refdb.
+	 *
+	 * A refdb implementation must provide this function.
+	 *
+	 * @arg ref The reference to persist. May either be a symbolic or
+	 *          direct reference.
+	 * @arg force Whether to write the reference if a reference with the
+	 *            same name already exists.
+	 * @arg who The person updating the reference. Shall be used to create
+	 *          a reflog entry.
+	 * @arg message The message detailing what kind of reference update is
+	 *              performed. Shall be used to create a reflog entry.
+	 * @arg old If not `NULL` and `force` is not set, then the
+	 *          implementation needs to ensure that the reference is currently at
+	 *          the given OID before writing the new value. If both `old`
+	 *          and `old_target` are `NULL`, then the reference should not
+	 *          exist at the point of writing.
+	 * @arg old_target If not `NULL` and `force` is not set, then the
+	 *                 implementation needs to ensure that the symbolic
+	 *                 reference is currently at the given target before
+	 *                 writing the new value. If both `old` and
+	 *                 `old_target` are `NULL`, then the reference should
+	 *                 not exist at the point of writing.
+	 * @return `0` on success, otherwise a negative error code.
 	 */
 	int GIT_CALLBACK(write)(git_refdb_backend *backend,
 		     const git_reference *ref, int force,
 		     const git_signature *who, const char *message,
 		     const git_oid *old, const char *old_target);
 
+	/**
+	 * Rename a reference in the refdb.
+	 *
+	 * A refdb implementation must provide this function.
+	 *
+	 * @arg out The implementation shall set this to the newly created
+	 *          reference or `NULL` on error.
+	 * @arg old_name The current name of the reference that is to be renamed.
+	 * @arg new_name The new name that the old reference shall be renamed to.
+	 * @arg force Whether to write the reference if a reference with the
+	 *            target name already exists.
+	 * @arg who The person updating the reference. Shall be used to create
+	 *          a reflog entry.
+	 * @arg message The message detailing what kind of reference update is
+	 *              performed. Shall be used to create a reflog entry.
+	 * @return `0` on success, otherwise a negative error code.
+	 */
 	int GIT_CALLBACK(rename)(
 		git_reference **out, git_refdb_backend *backend,
 		const char *old_name, const char *new_name, int force,
 		const git_signature *who, const char *message);
 
 	/**
-	 * Deletes the given reference (and if necessary its reflog)
-	 * from the refdb.  A refdb implementation must provide this
-	 * function.
+	 * Deletes the given reference from the refdb.
+	 *
+	 * If it exists, its reflog should be deleted as well.
+	 *
+	 * A refdb implementation must provide this function.
+	 *
+	 * @arg ref_name The name of the reference name that shall be deleted.
+	 * @arg old_id If not `NULL` and `force` is not set, then the
+	 *             implementation needs to ensure that the reference is currently at
+	 *             the given OID before writing the new value.
+	 * @arg old_target If not `NULL` and `force` is not set, then the
+	 *                 implementation needs to ensure that the symbolic
+	 *                 reference is currently at the given target before
+	 *                 writing the new value.
+	 * @return `0` on success, otherwise a negative error code.
 	 */
 	int GIT_CALLBACK(del)(git_refdb_backend *backend, const char *ref_name, const git_oid *old_id, const char *old_target);
 
 	/**
 	 * Suggests that the given refdb compress or optimize its references.
-	 * This mechanism is implementation specific.  (For on-disk reference
-	 * databases, this may pack all loose references.)    A refdb
-	 * implementation may provide this function; if it is not provided,
-	 * nothing will be done.
+	 *
+	 * This mechanism is implementation specific. For on-disk reference
+	 * databases, this may pack all loose references.
+	 *
+	 * A refdb implementation may provide this function; if it is not
+	 * provided, nothing will be done.
+	 *
+	 * @return `0` on success a negative error code otherwise
 	 */
 	int GIT_CALLBACK(compress)(git_refdb_backend *backend);
 
 	/**
 	 * Query whether a particular reference has a log (may be empty)
+	 *
+	 * Shall return 1 if it has a reflog, 0 it it doesn't and negative in
+	 * case an error occurred.
+	 *
+	 * A refdb implementation must provide this function.
+	 *
+	 * @return `0` on success, `1` if the reflog for the given reference
+	 *         exists, a negative error code otherwise
 	 */
 	int GIT_CALLBACK(has_log)(git_refdb_backend *backend, const char *refname);
 
 	/**
 	 * Make sure a particular reference will have a reflog which
 	 * will be appended to on writes.
+	 *
+	 * A refdb implementation must provide this function.
+	 *
+	 * @return `0` on success, a negative error code otherwise
 	 */
 	int GIT_CALLBACK(ensure_log)(git_refdb_backend *backend, const char *refname);
 
 	/**
 	 * Frees any resources held by the refdb (including the `git_refdb_backend`
-	 * itself). A refdb backend implementation must provide this function.
+	 * itself).
+	 *
+	 * A refdb backend implementation must provide this function.
 	 */
 	void GIT_CALLBACK(free)(git_refdb_backend *backend);
 
 	/**
 	 * Read the reflog for the given reference name.
+	 *
+	 * A refdb implementation must provide this function.
+	 *
+	 * @return `0` on success, a negative error code otherwise
 	 */
 	int GIT_CALLBACK(reflog_read)(git_reflog **out, git_refdb_backend *backend, const char *name);
 
 	/**
 	 * Write a reflog to disk.
+	 *
+	 * A refdb implementation must provide this function.
+	 *
+	 * @arg reflog The complete reference log for a given reference. Note
+	 *             that this may contain entries that have already been
+	 *             written to disk.
+	 * @return `0` on success, a negative error code otherwise
 	 */
 	int GIT_CALLBACK(reflog_write)(git_refdb_backend *backend, git_reflog *reflog);
 
 	/**
-	 * Rename a reflog
+	 * Rename a reflog.
+	 *
+	 * A refdb implementation must provide this function.
+	 *
+	 * @arg old_name The name of old reference whose reflog shall be renamed from.
+	 * @arg new_name The name of new reference whose reflog shall be renamed to.
+	 * @return `0` on success, a negative error code otherwise
 	 */
 	int GIT_CALLBACK(reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name);
 
 	/**
 	 * Remove a reflog.
+	 *
+	 * A refdb implementation must provide this function.
+	 *
+	 * @arg name The name of the reference whose reflog shall be deleted.
+	 * @return `0` on success, a negative error code otherwise
 	 */
 	int GIT_CALLBACK(reflog_delete)(git_refdb_backend *backend, const char *name);
 
 	/**
-	 * Lock a reference. The opaque parameter will be passed to the unlock function
+	 * Lock a reference.
+	 *
+	 * A refdb implementation may provide this function; if it is not
+	 * provided, the transaction API will fail to work.
+	 *
+	 * @arg payload_out Opaque parameter that will be passed verbosely to
+	 *                  `unlock`.
+	 * @arg refname Reference that shall be locked.
+	 * @return `0` on success, a negative error code otherwise
 	 */
 	int GIT_CALLBACK(lock)(void **payload_out, git_refdb_backend *backend, const char *refname);
 
 	/**
-	 * Unlock a reference. Only one of target or symbolic_target
-	 * will be set. success indicates whether to update the
-	 * reference or discard the lock (if it's false)
+	 * Unlock a reference.
+	 *
+	 * Only one of target or symbolic_target will be set.
+	 * `success` will be true if the reference should be update, false if
+	 * the lock must be discarded.
+	 *
+	 * A refdb implementation must provide this function if a `lock`
+	 * implementation is provided.
+	 *
+	 * @arg payload The payload returned by `lock`.
+	 * @arg success `1` if a reference should be updated, `2` if
+	 *              a reference should be deleted, `0` if the lock must be
+	 *              discarded.
+	 * @arg update_reflog `1` in case the reflog should be updated, `0`
+	 *                    otherwise.
+	 * @arg ref The reference which should be unlocked.
+	 * @arg who The person updating the reference. Shall be used to create
+	 *          a reflog entry in case `update_reflog` is set.
+	 * @arg message The message detailing what kind of reference update is
+	 *              performed. Shall be used to create a reflog entry in
+	 *              case `update_reflog` is set.
+	 * @return `0` on success, a negative error code otherwise
 	 */
 	int GIT_CALLBACK(unlock)(git_refdb_backend *backend, void *payload, int success, int update_reflog,
 		      const git_reference *ref, const git_signature *sig, const char *message);