Add basic tree documentation

1 files changed, 85 insertions, 0 deletions

diff --git a/lib/gall/tree.lua b/lib/gall/tree.lua
index ac13dc3..6c57ee0 100644
--- a/lib/gall/tree.lua
+++ b/lib/gall/tree.lua
@@ -46,6 +46,39 @@ local function unescape_filename(fn)
    return (zfn:gsub("%z", "\\"))
 end
 
+---
+-- Representation of a tree in a Git repository.
+--
+-- Apart from the @{diff_to} method which will mask an entry called `diff_to`,
+-- all the fields of a tree instance are the entries in the Git tree.
+--
+-- The values of those fields are tables with `permissions`, `name`, `type`,
+-- and `obj` entries.
+--
+-- @type tree
+
+---
+-- Generate the delta between two trees
+--
+-- Treedelta entries are tables containing:
+--
+-- * Start mode and end mode
+-- * Start kind and end kin
+-- * Start sha and end sha
+-- * An indication of the action
+-- * An optional score of the action
+-- * The filename in question
+-- * If a copy or rename, src_name and dst_name too
+--
+-- The treedelta table is both an array of those entries and a map keyed on
+-- the filename.
+--
+-- @function diff_to
+-- @tparam tree other Another tree instance
+-- @treturn[1] table The tree delta
+-- @treturn[2] nil Nil on error
+-- @treturn[2] string The error message
+
 function tree_method:diff_to(other)
    -- Generate a diff from self to other
    local repo = repos[self]
@@ -144,6 +177,19 @@ local treemeta = {
    __tostring = treetostring,
 }
 
+--- @section end
+
+---
+-- Create a new tree instance representing the given raw object
+--
+-- Trees are unrealised by default, use @{realise} to cause their data to
+-- be loaded into Lua if you want to iterate the tree.
+--
+-- @function new
+-- @tparam repository repo The repository in which the tree can be found
+-- @tparam object obj The raw object representing the tree
+-- @treturn tree The tree instance for the given raw object
+
 local function _new(repo, obj)
    local ret = setmetatable({}, treemeta)
    objs[ret] = obj
@@ -151,6 +197,16 @@ local function _new(repo, obj)
    return ret
 end
 
+---
+-- Realise a tree object
+--
+-- Tree objects are unrealised by default and realise themselves when you
+-- first access their fields.  You can call this function up-front if you
+-- want to force a tree to be realised first.
+--
+-- @function realise
+-- @tparam tree t The tree to realise
+
 local function _realise(t)
    if not parsed[t] then
       local ignored = t[parsed]
@@ -158,6 +214,20 @@ local function _realise(t)
    return t
 end
 
+---
+-- Flatten a tree into a single table.
+--
+-- Normally a tree consists of leaf -> data mappings.  To flatten a tree
+-- we walk the tree finding tree objects inside it and add those to the
+-- outer tree with their names separated by '/' which is how git does things.
+--
+-- Use this on a top-level tree to get a table mapping all entries in that
+-- tree and any trees beneath it.
+--
+-- @function flatten
+-- @tparam tree t The tree to flatten
+-- @treturn table The flattened tree
+
 local function _flatten(t)
    local ret = {}
    local function _inner_flatten(pfx, tt)
@@ -175,6 +245,16 @@ local function _flatten(t)
    return ret
 end
 
+---
+-- Create a tree instance representing the given flat tree
+--
+-- @function create
+-- @tparam repository repo The repository in which to create the tree(s)
+-- @tparam table flat_tree A flat tree (of the kind returned by @{flatten})
+-- @treturn[1] tree The tree instance representing the top level of the tree
+-- @treturn[2] nil Nil on error
+-- @treturn[2] string The error message
+
 local function _create(repo, flat_tree)
    local function __store(tree, element, content)
       local prefix, suffix = element:match("^([^/]+)/(.+)$")
@@ -234,6 +314,11 @@ local function _create(repo, flat_tree)
    return __treeify(t)
 end
 
+---
+-- The SHA1 OID of the empty tree
+--
+-- @field empty_sha
+
 return {
    realise = _realise,
    flatten = _flatten,