Finish docs for GitTree

base/libgit2/tree.jl

@@ -1,11 +1,16 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
 """
-Traverse the entries in a tree and its subtrees in post or pre order.
+    treewalk(f::Function, tree::GitTree, payload=Any[], post::Bool = false)
+
+Traverse the entries in `tree` and its subtrees in post or pre order.
 
 Function parameter should have following signature:
 
     (Cstring, Ptr{Void}, Ptr{Void}) -> Cint
+
+A negative value returned from `f` stops the tree walk. A positive value means
+that the entry will be skipped if `post` is `false`.
 """
 function treewalk(f::Function, tree::GitTree, payload=Any[], post::Bool = false)
     cbf = cfunction(f, Cint, Tuple{Cstring, Ptr{Void}, Ptr{Void}})
@@ -19,21 +24,42 @@ end
 repository(tree::GitTree) = tree.owner
 repository(te::GitTreeEntry) = repository(te.owner)
 
+"""
+    filename(te::GitTreeEntry)
+
+Return the filename of the object on disk to which `te` refers.
+"""
 function filename(te::GitTreeEntry)
     str = ccall((:git_tree_entry_name, :libgit2), Cstring, (Ptr{Void},), te.ptr)
     str != C_NULL && return unsafe_string(str)
     return nothing
 end
 
+"""
+    filemode(te::GitTreeEntry) -> Cint
+
+Return the UNIX filemode of the object on disk to which `te` refers as an integer.
+"""
 function filemode(te::GitTreeEntry)
     return ccall((:git_tree_entry_filemode, :libgit2), Cint, (Ptr{Void},), te.ptr)
 end
 
+"""
+    entrytype(te::GitTreeEntry)
+
+Return the type of the object to which `te` refers. The result will be
+one of the types which [`objtype`](@ref) returns, e.g. a `GitTree` or `GitBlob`.
+"""
 function entrytype(te::GitTreeEntry)
     otype = ccall((:git_tree_entry_type, :libgit2), Cint, (Ptr{Void},), te.ptr)
     return objtype(Consts.OBJECT(otype))
 end
 
+"""
+    entryid(te::GitTreeEntry)
+
+Return the [`GitHash`](@ref) of the object to which `te` refers.
+"""
 function entryid(te::GitTreeEntry)
     oid_ptr = ccall((:git_tree_entry_id, :libgit2), Ptr{UInt8}, (Ptr{Void},), te.ptr)
     return GitHash(oid_ptr)
@@ -53,6 +79,20 @@ function Base.getindex(tree::GitTree, i::Integer)
     return GitTreeEntry(tree, te_ptr, false)
 end
 
+"""
+    (::Type{T})(te::GitTreeEntry) where T<:GitObject
+
+Get the git object to which `te` refers and return it as its actual type (the type
+[`entrytype`](@ref) would show), for instance a `GitBlob` or `GitTag`.
+
+# Examples
+```julia
+tree = LibGit2.GitTree(repo, "HEAD^{tree}")
+tree_entry = tree[1]
+blob = LibGit2.GitBlob(tree_entry)
+```
+"""
+function GitObject(e::GitTreeEntry) end
 function (::Type{T})(te::GitTreeEntry) where T<:GitObject
     repo = repository(te)
     obj_ptr_ptr = Ref{Ptr{Void}}(C_NULL)

doc/src/devdocs/libgit2.md

@@ -74,6 +74,8 @@ Base.LibGit2.credentials_cb
 Base.LibGit2.default_signature
 Base.LibGit2.delete_branch
 Base.LibGit2.diff_files
+Base.LibGit2.entryid
+Base.LibGit2.entrytype
 Base.LibGit2.fetch
 Base.LibGit2.fetchheads
 Base.LibGit2.fetch_refspecs
@@ -83,6 +85,8 @@ Base.LibGit2.merge!(::Base.LibGit2.GitRepo; ::Any...)
 Base.LibGit2.ffmerge!
 Base.LibGit2.fullname
 Base.LibGit2.features
+Base.LibGit2.filename
+Base.LibGit2.filemode
 Base.LibGit2.get_creds!
 Base.LibGit2.gitdir
 Base.LibGit2.head
@@ -140,4 +144,5 @@ Base.LibGit2.url
 Base.LibGit2.version
 Base.LibGit2.with
 Base.LibGit2.workdir
+Base.LibGit2.GitObject(::Base.LibGit2.GitTreeEntry)
 ```