Move git_reference__alloc to include/git2/sys

Create a new include/git2/sys/refs.h and move the reference alloc
functions there.  Also fix some documentation issues and some
minor code cleanups.

9 files changed, 78 insertions, 52 deletions

diff --git a/include/git2/refdb.h b/include/git2/refdb.h
index 9278b1116..a315876ae 100644
--- a/include/git2/refdb.h
+++ b/include/git2/refdb.h
@@ -22,25 +22,6 @@
 GIT_BEGIN_DECL
 
 /**
- * Create a new reference.  Either an oid or a symbolic target must be
- * specified.
- *
- * @param refdb the reference database to associate with this reference
- * @param name the reference name
- * @param oid the object id for a direct reference
- * @param symbolic the target for a symbolic reference
- * @return the created git_reference or NULL on error
- */
-GIT_EXTERN(git_reference *) git_reference__alloc(
-	const char *name,
-	const git_oid *oid,
-	const git_oid *peel);
-
-GIT_EXTERN(git_reference *) git_reference__alloc_symbolic(
-	const char *name,
-	const char *target);
-
-/**
  * Create a new reference database with no backends.
  *
  * Before the Ref DB can be used for read/writing, a custom database
diff --git a/include/git2/sys/refdb_backend.h b/include/git2/sys/refdb_backend.h
index dcdf7bcb8..d5f599fec 100644
--- a/include/git2/sys/refdb_backend.h
+++ b/include/git2/sys/refdb_backend.h
@@ -4,8 +4,8 @@
  * 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_git_refdb_backend_h__
-#define INCLUDE_git_refdb_backend_h__
+#ifndef INCLUDE_sys_git_refdb_backend_h__
+#define INCLUDE_sys_git_refdb_backend_h__
 
 #include "git2/common.h"
 #include "git2/types.h"
@@ -30,7 +30,7 @@ struct git_refdb_backend {
 	 */
 	int (*exists)(
 		int *exists,
-		struct git_refdb_backend *backend,
+		git_refdb_backend *backend,
 		const char *ref_name);
 
 	/**
@@ -39,7 +39,7 @@ struct git_refdb_backend {
 	 */
 	int (*lookup)(
 		git_reference **out,
-		struct git_refdb_backend *backend,
+		git_refdb_backend *backend,
 		const char *ref_name);
 
 	/**
@@ -47,7 +47,7 @@ struct git_refdb_backend {
 	 * provide this function.
 	 */
 	int (*foreach)(
-		struct git_refdb_backend *backend,
+		git_refdb_backend *backend,
 		unsigned int list_flags,
 		git_reference_foreach_cb callback,
 		void *payload);
@@ -59,7 +59,7 @@ struct git_refdb_backend {
 	 * against the glob.
 	 */
 	int (*foreach_glob)(
-		struct git_refdb_backend *backend,
+		git_refdb_backend *backend,
 		const char *glob,
 		unsigned int list_flags,
 		git_reference_foreach_cb callback,
@@ -69,13 +69,13 @@ struct git_refdb_backend {
 	 * Writes the given reference to the refdb.  A refdb implementation
 	 * must provide this function.
 	 */
-	int (*write)(struct git_refdb_backend *backend, const git_reference *ref);
+	int (*write)(git_refdb_backend *backend, const git_reference *ref);
 
 	/**
 	 * Deletes the given reference from the refdb.  A refdb implementation
 	 * must provide this function.
 	 */
-	int (*delete)(struct git_refdb_backend *backend, const git_reference *ref);
+	int (*delete)(git_refdb_backend *backend, const git_reference *ref);
 
 	/**
 	 * Suggests that the given refdb compress or optimize its references.
@@ -84,31 +84,41 @@ struct git_refdb_backend {
 	 * implementation may provide this function; if it is not provided,
 	 * nothing will be done.
 	 */
-	int (*compress)(struct git_refdb_backend *backend);
+	int (*compress)(git_refdb_backend *backend);
 
 	/**
 	 * Frees any resources held by the refdb.  A refdb implementation may
 	 * provide this function; if it is not provided, nothing will be done.
 	 */
-	void (*free)(struct git_refdb_backend *backend);
+	void (*free)(git_refdb_backend *backend);
 };
 
 #define GIT_ODB_BACKEND_VERSION 1
 #define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION}
 
 /**
- * Constructors for default refdb backends.
+ * Constructors for default filesystem-based refdb backend
+ *
+ * Under normal usage, this is called for you when the repository is
+ * opened / created, but you can use this to explicitly construct a
+ * filesystem refdb backend for a repository.
+ *
+ * @param backend_out Output pointer to the git_refdb_backend object
+ * @param repo Git repository to access
+ * @return 0 on success, <0 error code on failure
  */
 GIT_EXTERN(int) git_refdb_backend_fs(
-	struct git_refdb_backend **backend_out,
+	git_refdb_backend **backend_out,
 	git_repository *repo);
 
 /**
  * Sets the custom backend to an existing reference DB
  *
+ * The `git_refdb` will take ownership of the `git_refdb_backend` so you
+ * should NOT free it after calling this function.
+ *
  * @param refdb database to add the backend to
  * @param backend pointer to a git_refdb_backend instance
- * @param priority Value for ordering the backends queue
  * @return 0 on success; error code otherwise
  */
 GIT_EXTERN(int) git_refdb_set_backend(
diff --git a/include/git2/sys/refs.h b/include/git2/sys/refs.h
new file mode 100644
index 000000000..85963258c
--- /dev/null
+++ b/include/git2/sys/refs.h
@@ -0,0 +1,38 @@
+/*
+ * 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_refdb_h__
+#define INCLUDE_sys_git_refdb_h__
+
+#include "git2/common.h"
+#include "git2/types.h"
+#include "git2/oid.h"
+
+/**
+ * Create a new direct reference from an OID.
+ *
+ * @param name the reference name
+ * @param oid the object id for a direct reference
+ * @param symbolic the target for a symbolic reference
+ * @return the created git_reference or NULL on error
+ */
+GIT_EXTERN(git_reference *) git_reference__alloc(
+	const char *name,
+	const git_oid *oid,
+	const git_oid *peel);
+
+/**
+ * Create a new symbolic reference.
+ *
+ * @param name the reference name
+ * @param symbolic the target for a symbolic reference
+ * @return the created git_reference or NULL on error
+ */
+GIT_EXTERN(git_reference *) git_reference__alloc_symbolic(
+	const char *name,
+	const char *target);
+
+#endif
diff --git a/src/refdb.c b/src/refdb.c
index 0675be638..33a1934d1 100644
--- a/src/refdb.c
+++ b/src/refdb.c
@@ -58,15 +58,19 @@ int git_refdb_open(git_refdb **out, git_repository *repo)
 	return 0;
 }
 
-int git_refdb_set_backend(git_refdb *db, git_refdb_backend *backend)
+static void refdb_free_backend(git_refdb *db)
 {
 	if (db->backend) {
-		if(db->backend->free)
+		if (db->backend->free)
 			db->backend->free(db->backend);
 		else
 			git__free(db->backend);
 	}
+}
 
+int git_refdb_set_backend(git_refdb *db, git_refdb_backend *backend)
+{
+	refdb_free_backend(db);
 	db->backend = backend;
 
 	return 0;
@@ -76,22 +80,15 @@ int git_refdb_compress(git_refdb *db)
 {
 	assert(db);
 
-	if (db->backend->compress) {
+	if (db->backend->compress)
 		return db->backend->compress(db->backend);
-	}
 
 	return 0;
 }
 
 static void refdb_free(git_refdb *db)
 {
-	if (db->backend) {
-		if(db->backend->free)
-			db->backend->free(db->backend);
-		else
-			git__free(db->backend);
-	}
-
+	refdb_free_backend(db);
 	git__free(db);
 }
 
@@ -115,14 +112,13 @@ int git_refdb_lookup(git_reference **out, git_refdb *db, const char *ref_name)
 	git_reference *ref;
 	int error;
 
-	assert(db && db->backend && ref_name);
-
-	*out = NULL;
+	assert(db && db->backend && out && ref_name);
 
-	if ((error = db->backend->lookup(&ref, db->backend, ref_name)) == 0)
-	{
+	if (!(error = db->backend->lookup(&ref, db->backend, ref_name))) {
 		ref->db = db;
 		*out = ref;
+	} else {
+		*out = NULL;
 	}
 
 	return error;
diff --git a/src/refdb.h b/src/refdb.h
index 0969711b9..047113ac8 100644
--- a/src/refdb.h
+++ b/src/refdb.h
@@ -41,6 +41,6 @@ int git_refdb_foreach_glob(
 
 int git_refdb_write(git_refdb *refdb, const git_reference *ref);
 
-int git_refdb_delete(struct git_refdb *refdb, const git_reference *ref);
+int git_refdb_delete(git_refdb *refdb, const git_reference *ref);
 
 #endif
diff --git a/src/refdb_fs.c b/src/refdb_fs.c
index 4d5d6006d..443871005 100644
--- a/src/refdb_fs.c
+++ b/src/refdb_fs.c
@@ -19,6 +19,7 @@
 #include <git2/object.h>
 #include <git2/refdb.h>
 #include <git2/sys/refdb_backend.h>
+#include <git2/sys/refs.h>
 
 GIT__USE_STRMAP;
 
diff --git a/src/refs.c b/src/refs.c
index d9291e56f..9c6684a5a 100644
--- a/src/refs.c
+++ b/src/refs.c
@@ -19,6 +19,7 @@
 #include <git2/branch.h>
 #include <git2/refs.h>
 #include <git2/refdb.h>
+#include <git2/sys/refs.h>
 
 GIT__USE_STRMAP;
 
@@ -44,8 +45,7 @@ static git_reference *alloc_ref(const char *name)
 }
 
 git_reference *git_reference__alloc_symbolic(
-	const char *name,
-	const char *target)
+	const char *name, const char *target)
 {
 	git_reference *ref;
 
diff --git a/tests-clar/refdb/inmemory.c b/tests-clar/refdb/inmemory.c
index 2c76d4192..243b5bb37 100644
--- a/tests-clar/refdb/inmemory.c
+++ b/tests-clar/refdb/inmemory.c
@@ -63,7 +63,6 @@ void test_refdb_inmemory__initialize(void)
 	cl_git_pass(git_repository_refdb(&refdb, repo));
 	cl_git_pass(refdb_backend_test(&refdb_backend, repo));
 	cl_git_pass(git_refdb_set_backend(refdb, refdb_backend));
-	git_refdb_free(refdb);
 
 	ref_file_foreach(repo, unlink_ref);
 
diff --git a/tests-clar/refdb/testdb.h b/tests-clar/refdb/testdb.h
index 49d1cb1d0..a0d1bbc48 100644
--- a/tests-clar/refdb/testdb.h
+++ b/tests-clar/refdb/testdb.h
@@ -1,6 +1,7 @@
 #include <git2/errors.h>
 #include <git2/repository.h>
 #include <git2/refdb.h>
+#include <git2/sys/refs.h>
 #include <git2/sys/refdb_backend.h>
 
 int refdb_backend_test(