Finish docs for GitTree (JuliaLang#23451)

* Finish docs for GitTree

base/libgit2/tree.jl

@@ -1,11 +1,21 @@
 # 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)
 
-Function parameter should have following signature:
+Traverse the entries in `tree` and its subtrees in post or pre order. Preorder
+means beginning at the root and then traversing the leftmost subtree (and
+recursively on down through that subtree's leftmost subtrees) and moving right
+through the subtrees. Postorder means beginning at the bottom of the leftmost
+subtree, traversing upwards through it, then traversing the next right subtree
+(again beginning at the bottom) and finally visiting the tree root last of all.
+
+The function parameter `f` 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 +29,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 +84,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

@@ -76,6 +76,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
@@ -85,6 +87,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.@githash_str
@@ -147,4 +151,5 @@ Base.LibGit2.version
 Base.LibGit2.with
 Base.LibGit2.with_warn
 Base.LibGit2.workdir
+Base.LibGit2.GitObject(::Base.LibGit2.GitTreeEntry)
 ```