Add basic documentation for gall.ll.git2

1 files changed, 117 insertions, 0 deletions

diff --git a/lib/gall/ll/git2.c b/lib/gall/ll/git2.c
index 9188ab8..8fee1dc 100644
--- a/lib/gall/ll/git2.c
+++ b/lib/gall/ll/git2.c
@@ -5,6 +5,12 @@
  * Copyright 2014 Daniel Silverstone <dsilvers@digital-scurf.org>
  */
 
+/**
+ * Low-Level C binding for Gall's use of libgit2.
+ *
+ * @module gall.ll.git2
+ */
+
 #include <lua.h>
 #include <lauxlib.h>
 #include "git2.h"
@@ -57,6 +63,19 @@ static int L_gc_repo(lua_State *L)
 	return 0;
 }
 
+/**
+ * Open a repository from disk.
+ *
+ * This function opens a repository on disk using libgit2.  This low level
+ * repository type can be used in routines such as @{lookup_symbolic_ref} or
+ * @{lookup_sha_from_ref}.
+ *
+ * @function open_repo
+ * @tparam string repopath The path to the repository
+ * @treturn llrepo The repository (or nil on error)
+ * @treturn string An error message (if repo is nil)
+ */
+
 /* Trivial Repository binding, GC will free the repo */
 static int L_open_repo(lua_State *L)
 {
@@ -82,6 +101,16 @@ static int L_open_repo(lua_State *L)
 	return 1;
 }
 
+/**
+ * Dereference a symbolic ref.
+ *
+ * @function lookup_symbolic_ref
+ * @tparam llrepo repository The repository to look up the ref in.
+ * @tparam string ref The symbolic ref name to dereference.
+ * @treturn string The symbolic referent (or nil on error)
+ * @treturn string The error message if the referent is nil
+ */
+
 static int L_lookup_symbolic_ref(lua_State *L)
 {
 	git_repository *repo = to_repo(L, 1);
@@ -110,6 +139,16 @@ static int format_oid(lua_State *L, const git_oid *oid)
 	return 1;
 }
 
+/**
+ * Lookup the SHA1 pointed at by a reference.
+ *
+ * @function lookup_sha_from_ref
+ * @tparam llrepo repository The repository to look up the reference in.
+ * @tparam string ref The reference to look up.
+ * @treturn string The OID (SHA1) of the referent (or nil on error).
+ * @treturn string The error message if the OID is nil.
+ */
+
 static int L_lookup_sha_from_ref(lua_State *L)
 {
 	git_repository *repo = to_repo(L, 1);
@@ -131,6 +170,17 @@ static int parse_oid(lua_State *L, int spos, git_oid *oid)
 	return 0;
 }
 
+/**
+ * Calculate the merge-base of a pair of OIDs.
+ *
+ * @function merge_base
+ * @tparam llrepo repository The repository to calculate the merge-base within.
+ * @tparam string left The left-side of the merge as an OID.
+ * @tparam string right The right-side of the merge as an OID.
+ * @treturn string The OID of the merge-base if available, or nil on error.
+ * @treturn string The error message if the merge-base is nil.
+ */
+
 static int L_merge_base(lua_State *L)
 {
 	git_repository *repo = to_repo(L, 1);
@@ -151,6 +201,17 @@ static int L_merge_base(lua_State *L)
 	return push_git2_error(L, ret);
 }
 
+/**
+ * Set a symbolic reference's referent.
+ *
+ * @function set_symbolic_ref
+ * @tparam llrepo repository The repository to set the reference within.
+ * @tparam string reference The reference to set.
+ * @tparam string referent The reference name to act as referent for reference.
+ * @treturn boolean On success, true, otherwise nil.
+ * @treturn string On failure, the error message.
+ */
+
 static int L_set_symbolic_ref(lua_State *L)
 {
 	git_repository *repo = to_repo(L, 1);
@@ -176,6 +237,16 @@ static int L_gc_odb_object(lua_State *L)
 	return 0;
 }
 
+/**
+ * Retrieve a generic object from git.
+ *
+ * @function get_object
+ * @tparam llrepo repository The repository to retrieve the object from.
+ * @tparam string oid The object to return (as a SHA1)
+ * @treturn gitobject The git object whose OID was provided (or nil)
+ * @treturn string The error message if the returned git object was nil
+ */
+
 static int L_get_object(lua_State *L)
 {
 	git_odb *odb = to_odb(L, 1);
@@ -191,6 +262,14 @@ static int L_get_object(lua_State *L)
 	return 1;
 }
 
+/**
+ * Retrieve the size of a git object.
+ *
+ * @function get_object_size
+ * @tparam gitobject obj The object whose size you wish to query
+ * @treturn number The size of the object in bytes
+ */
+
 static int L_get_object_size(lua_State *L)
 {
 	git_odb_object **obj = lua_touserdata(L, 1);
@@ -237,6 +316,14 @@ static void push_object_type_str(lua_State *L, git_otype ty)
 	}
 }
 
+
+/**
+ * Retrieve a git object's type
+ *
+ * @function get_object_type
+ * @tparam gitobject obj The object whose type you wish to retrieve.
+ * @treturn string The type of the object provided.
+ */
 static int L_get_object_type(lua_State *L)
 {
 	git_odb_object **obj = lua_touserdata(L, 1);
@@ -244,6 +331,14 @@ static int L_get_object_type(lua_State *L)
 	return 1;
 }
 
+/**
+ * Retrieve the raw content of an object
+ *
+ * @function get_object_raw
+ * @tparam gitobject obj The object whose content you wish to retrieve.
+ * @treturn string The raw content of the object as a string.
+ */
+
 static int L_get_object_raw(lua_State *L)
 {
 	git_odb_object **obj = lua_touserdata(L, 1);
@@ -252,6 +347,19 @@ static int L_get_object_raw(lua_State *L)
 	return 1;
 }
 
+/**
+ * Retrieve a tree's content as a table
+ *
+ * The returned table is a numerically indexed table of entries.  Each entry
+ * is a table with `name` (string) `sha` (string) and `perms` (number) entries.
+ *
+ * @function get_tree_table
+ * @tparam llrepo repository The repository to query for the tree's content.
+ * @tparam string tree The OID of the tree object to retrieve
+ * @treturn table The tree as a table, or nil on error
+ * @treturn string The error message if the returned tree table is nil
+ */
+
 static int L_get_tree_table(lua_State *L)
 {
 	git_repository *repo = to_repo(L, 1);
@@ -285,6 +393,15 @@ static int L_get_tree_table(lua_State *L)
 	return 1;
 }
 
+/**
+ * The version of libgit2 which this instance of gall was built against.
+ *
+ * When Gall is compiled, the version of libgit2 is baked into the C binding
+ * to be checked against when run.
+ *
+ * @field LIBGIT2_VERSION
+ */
+
 int luaopen_gall_ll_git2(lua_State *L)
 {
 	lua_newtable(L);