Basic documentation for the commit object

1 files changed, 101 insertions, 0 deletions

diff --git a/lib/gall/commit.lua b/lib/gall/commit.lua
index bd6f341..ce1d375 100644
--- a/lib/gall/commit.lua
+++ b/lib/gall/commit.lua
@@ -19,6 +19,35 @@ local parsed = setmetatable({}, {__mode="k"})
 
 local _new
 
+---
+-- Who, when
+--
+-- Encapsulation of git's author/committer who and when data
+--
+-- @type whowhen
+
+---
+-- The "real" name of the person.
+--
+-- @field realname
+
+---
+-- The email address of the person.
+--
+-- @field email
+
+---
+-- The UNIX time (seconds since epoch) for the signature line
+--
+-- @field unixtime
+
+---
+-- The timezone in which the signature took place (+/-HHHH)
+--
+-- @field timezone
+
+--- @section end
+
 local function parse_person(pers)
    local real, email, when, tz = pers:match("^(.-) <([^>]+)> ([0-9]+) ([+-][0-9]+)$")
    return {
@@ -97,11 +126,62 @@ local function committostring(commit)
    return "<GitCommit(" .. tostring(objs[commit].sha) .. ") in " .. tostring(repos[commit]) .. ">"
 end
 
+---
+-- Commit object.
+--
+-- @type commit
+
+---
+-- The tree object referenced by this commit.
+--
+-- @field tree
+-- @see gall.tree
+
+---
+-- The author of the commit as a @{whowhen} object
+--
+-- @field author
+
+---
+-- The committer of the commit as a @{whowhen} object
+--
+-- @field committer
+
+---
+-- The parents of the commit (zero or more @{commit} objects)
+--
+-- @field parents
+
+---
+-- The commit message
+--
+-- @field message
+
+---
+-- The signature on the commit (if present)
+--
+-- @field signature
+
+---
+-- The SHA1 OID of the commit
+--
+-- @field sha
+
+--- @section end
+
 local commitmeta = {
    __index = commitindex,
    __tostring = committostring
 }
 
+---
+-- Instantiate a new @{commit} object for the given raw git object
+--
+-- @function new
+-- @tparam repository repo The repository containing the commit
+-- @tparam object obj The raw git object for the commit
+-- @treturn commit The new commit instance
+
 local function _new(repo, obj)
    local ret =  setmetatable({}, commitmeta)
    objs[ret] = obj
@@ -109,6 +189,27 @@ local function _new(repo, obj)
    return ret
 end
 
+---
+-- Create a new commit object in the repository.
+--
+-- The given data must contain all of:
+--
+-- * tree - The tree object for the commit
+-- * author - The author (as a table of realname and email)
+-- * committer - The committer (as a table of realname and email)
+-- * message - The commit message
+--
+-- It may optionally contain:
+--
+-- * parents - The list of parent commit objects.
+--
+-- @function create
+-- @tparam repository repo The repository to create the commit in
+-- @tparam table data The commit data
+-- @treturn[1] commit The newly added commit object
+-- @treturn[2] nil Nil on error
+-- @treturn[2] string The error message
+
 local function _create(repo, data)
    if not data.tree then
       return nil, "No tree?"