Basic low-level object documentation

1 files changed, 61 insertions, 0 deletions

diff --git a/lib/gall/object.lua b/lib/gall/object.lua
index 32db03d..d6b9008 100644
--- a/lib/gall/object.lua
+++ b/lib/gall/object.lua
@@ -77,6 +77,52 @@ local objectmeta = {
    __tostring = _objecttostring
 }
 
+---
+-- Low level git object
+--
+-- @type object
+
+---
+-- The type of the object
+--
+-- @field type
+
+---
+-- The size of the object
+--
+-- @field size
+
+---
+-- The object's raw content
+--
+-- @field raw
+
+---
+-- The object's processed content.
+--
+-- * If the object is a commit, then this will be a @{commit} instance.
+-- * If the object is a tree, then this will be a @{tree} instance.
+-- * If the object is a tag, then this will be a @{tag} instance.
+--
+-- @field content
+
+---
+-- The object's OID (SHA1)
+--
+-- @field sha
+
+--- @section end
+
+---
+-- Create a new raw object.
+--
+-- Create a new instance of @{object} referring to the given SHA1 OID.
+--
+-- @function new
+-- @tparam repository repo The repository within which the object resides.
+-- @tparam string sha The SHA1 OID of the object in the repository.
+-- @treturn object The object instance encapsulating the given object.
+
 local function _new(repo, sha)
    local ret = setmetatable({sha=sha}, objectmeta)
    repos[ret] = repo
@@ -86,6 +132,21 @@ local function _new(repo, sha)
    return ret
 end
 
+---
+-- Create a new raw object.
+--
+-- Create a new raw object and insert it into the given repository.  This will
+-- not only create the @{object} instance but also insert it into the
+-- repository storage.
+--
+-- @function create
+-- @tparam repository repo The repository within which the object resides.
+-- @tparam string type The type of the object (e.g. blob or commit)
+-- @tparam string content The content to insert as the object's content.
+-- @treturn[1] object The object instance encapsulating the given object.
+-- @treturn[2] nil Nil on error
+-- @treturn[2] string The error message
+
 local function _create(repo, type, content)
    local why, sha = 
       repo:_run_with_input(content, ll.chomp,