Add gall.ll documentation

1 files changed, 60 insertions, 0 deletions

diff --git a/lib/gall/ll.lua b/lib/gall/ll.lua
index 839669d..98b6858 100644
--- a/lib/gall/ll.lua
+++ b/lib/gall/ll.lua
@@ -9,6 +9,27 @@
 ---
 -- Low level interface to Git
 --
+-- In addition to the documented functions below, the following Git subcommands
+-- are directly exposed as functions which are essentially like...
+--
+--    function gall.ll.FUNC(...)
+--        return gall.ll.rungit("FUNC", ...)
+--    end
+--
+-- ...but with correct handling of the tabular input to @{rungit}
+--
+-- The current full-list of those functions is:
+--
+-- * cat_file exposes `git cat-file`
+-- * symbolic_ref exposes `git symbolic-ref`
+-- * show_ref exposes `git show-ref`
+-- * hash_object exposes `git hash-object`
+-- * ls_tree exposes `git ls-tree`
+-- * init exposes `git init`
+-- * merge_base exposes `git merge-base`
+-- * rev_list exposes `git rev-list`
+-- * config exposes `git config`
+--
 -- @module gall.ll
 
 
@@ -30,6 +51,28 @@ local assert = assert
 
 local git_exe = "git"
 
+---
+-- Run the given git process.
+--
+-- The run parameters must contain:
+--
+-- * The `repo` (the value for `GIT_DIR`)
+-- * At least 1 list entry for the command line
+-- * Optionally an `env` table.
+-- * Optionally a string `stdin` to pass into the process
+-- * Optionally a `stdout` boolean which says whether to capture stdout
+-- * Optionally a `stderr` boolean which says whether to capture stderr
+--
+-- Additionally, if `stdout` or `stderr` are functions instead of booleans then
+-- they will be called to filter the stream after reading.
+--
+-- @function rungit
+-- @tparam table t Run parameters
+-- @treturn number Exit code
+-- @treturn string Contents of stdout
+-- @treturn string Contents of stderr
+-- @raise Function will assert if given no repository or if the subprocess is killed uncleanly
+
 local function _rungit(t)
    assert(t.repo, "No repository?")
 
@@ -82,6 +125,16 @@ local function _rungit(t)
    return why, stdout, stderr
 end
 
+---
+-- Get / Set the git executable
+--
+-- If `e` is provided, then it is set as the path, otherwise the current
+-- path is returned as-is.  By default, the Git executable is simply `git`.
+--
+-- @function get_set_git
+-- @tparam ?string e The path to the Git executable
+-- @treturn string The path to the Git executable
+
 local function get_set_git(e)
    if e then
       git_exe = e
@@ -89,6 +142,13 @@ local function get_set_git(e)
    return git_exe
 end
 
+---
+-- Remove a trailing newline if present.
+--
+-- @function chomp
+-- @tparam string s The string to chomp
+-- @treturn string `s` with a single trailing newline (if present) removed.
+
 local function _chomp(s)
    local rest = s:match("^(.*)\n$")
    return rest or s