Add documentation for tag

1 files changed, 79 insertions, 0 deletions

diff --git a/lib/gall/tag.lua b/lib/gall/tag.lua
index e0c3c3a..6beafaa 100644
--- a/lib/gall/tag.lua
+++ b/lib/gall/tag.lua
@@ -17,6 +17,35 @@ local objs = setmetatable({}, {__mode="k"})
 local repos = setmetatable({}, {__mode="k"})
 local parsed = setmetatable({}, {__mode="k"})
 
+---
+-- 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 {
@@ -78,6 +107,48 @@ local function tagindex(tag, field)
    return rawget(tag, field)
 end
 
+---
+-- Encapsulation of a tag object in a Git repository
+--
+-- @type tag
+
+---
+-- The object which has been tagged
+--
+-- @field object
+
+---
+-- The type of the tagged object
+--
+-- @field type
+
+---
+-- The tag name itself
+--
+-- @field tag
+
+---
+-- The tagger as a @{whowhen} instance.
+--
+-- @field tagger
+
+---
+-- The tagging message
+--
+-- @field message
+
+---
+-- The signature on the tag (if present)
+--
+-- @field signature
+
+---
+-- The SHA1 OID of the tag
+--
+-- @field sha
+
+--- @section end
+
 local function tagtostring(tag)
    return "<GitTag(" .. tostring(objs[tag].sha) .. ") in " .. tostring(repos[tag]) .. ">"
 end
@@ -87,6 +158,14 @@ local tagmeta = {
    __tostring = tagtostring
 }
 
+---
+-- Create a new @{tag} instance to represent a tag object in a repository.
+--
+-- @function new
+-- @tparam repository repo The repository containing the tag object.
+-- @tparam object obj The low level git object representing the tag.
+-- @treturn tag The tag object representing the tag.
+
 local function _new(repo, obj)
    local ret =  setmetatable({}, tagmeta)
    objs[ret] = obj