refdb: documentation

1 files changed, 57 insertions, 21 deletions

diff --git a/include/git2/sys/refdb_backend.h b/include/git2/sys/refdb_backend.h
index 2ed6efd5a..8e22c4f02 100644
--- a/include/git2/sys/refdb_backend.h
+++ b/include/git2/sys/refdb_backend.h
@@ -58,11 +58,12 @@ 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.
 	 */
 	int GIT_CALLBACK(exists)(
 		int *exists,
@@ -70,8 +71,9 @@ 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.
 	 */
 	int GIT_CALLBACK(lookup)(
 		git_reference **out,
@@ -88,82 +90,116 @@ struct git_refdb_backend {
 		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.
 	 */
 	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.
+	 */
 	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.
 	 */
 	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.
 	 */
 	int GIT_CALLBACK(compress)(git_refdb_backend *backend);
 
 	/**
 	 * Query whether a particular reference has a log (may be empty)
+	 *
+	 * A refdb implementation must provide this function.
 	 */
 	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.
 	 */
 	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.
 	 */
 	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.
 	 */
 	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.
 	 */
 	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.
 	 */
 	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.
+	 *
+	 * The opaque parameter will be passed to the unlock function.
+	 *
+	 * A refdb implementation may provide this function; if it is not
+	 * provided, the transaction API will fail to work.
 	 */
 	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.
 	 */
 	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);