refdb: documentation
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
diff --git a/include/git2/sys/refdb_backend.h b/include/git2/sys/refdb_backend.h
index 2ed6efd..8e22c4f 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);
diff --git a/src/refdb_fs.c b/src/refdb_fs.c
index a20f1eb..23bb19f 100644
--- a/src/refdb_fs.c
+++ b/src/refdb_fs.c
@@ -1904,7 +1904,7 @@ static int reflog_append(refdb_fs_backend *backend, const git_reference *ref, co
!(old && new))
return 0;
- /* From here on is_symoblic also means that it's HEAD */
+ /* From here on is_symbolic also means that it's HEAD */
if (old) {
git_oid_cpy(&old_id, old);