Merge pull request JuliaLang#20503 from JuliaLang/ksh/docgit5

MORE docs for libgit2

base/libgit2/repository.jl

@@ -18,6 +18,12 @@ function GitRepo(path::AbstractString)
     return GitRepo(repo_ptr_ptr[])
 end
 
+"""
+    LibGit2.GitRepoExt(path::AbstractString, flags::Cuint = Cuint(Consts.REPOSITORY_OPEN_DEFAULT))
+
+Opens a git repository at `path` with extended controls (for instance, if the current
+user must be a member of a special access group to read `path`).
+"""
 function GitRepoExt(path::AbstractString, flags::Cuint = Cuint(Consts.REPOSITORY_OPEN_DEFAULT))
     separator = @static is_windows() ? ";" : ":"
     repo_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
@@ -39,13 +45,26 @@ function cleanup(r::GitRepo)
     end
 end
 
+"""
+    LibGit2.init(path::AbstractString, bare::Bool=false) -> GitRepo
+
+Opens a new git repository at `path`. If `bare` is `false`,
+the working tree will be created in `path/.git`. If `bare`
+is `true`, no working directory will be created.
+"""
 function init(path::AbstractString, bare::Bool=false)
     repo_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
     @check ccall((:git_repository_init, :libgit2), Cint,
                 (Ptr{Ptr{Void}}, Cstring, Cuint), repo_ptr_ptr, path, bare)
     return GitRepo(repo_ptr_ptr[])
 end
 
+"""
+    LibGit2.head_oid(repo::GitRepo) -> GitHash
+
+Lookup the object id of the current HEAD of git
+repository `repo`.
+"""
 function head_oid(repo::GitRepo)
     head_ref = head(repo)
     try
@@ -55,6 +74,14 @@ function head_oid(repo::GitRepo)
     end
 end
 
+"""
+    LibGit2.headname(repo::GitRepo)
+
+Lookup the name of the current HEAD of git
+repository `repo`. If `repo` is currently
+detached, returns the name of the HEAD it's
+detached from.
+"""
 function headname(repo::GitRepo)
     with(head(repo)) do href
         if isattached(repo)

base/libgit2/status.jl

@@ -1,5 +1,14 @@
 # This file is a part of Julia. License is MIT: http://julialang.org/license
 
+"""
+    LibGit2.GitStatus(repo::GitRepo; status_opts=StatusOptions())
+
+Collect information about the status of each file in the git
+repository `repo` (e.g. is the file modified, staged, etc.).
+`status_opts` can be used to set various options, for instance
+whether or not to look at untracked files or whether to include
+submodules or not.
+"""
 function GitStatus(repo::GitRepo; status_opts=StatusOptions())
     stat_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
     @check ccall((:git_status_list_new, :libgit2), Cint,
@@ -23,6 +32,14 @@ function Base.getindex(status::GitStatus, i::Integer)
     return unsafe_load(entry_ptr)
 end
 
+"""
+    LibGit2.status(repo::GitRepo, path::String)
+
+Lookup the status of the file at `path` in the git
+repository `repo`. For instance, this can be used
+to check if the file at `path` has been modified
+and needs to be staged and committed.
+"""
 function status(repo::GitRepo, path::String)
     status_ptr = Ref{Cuint}(0)
     ret =  ccall((:git_status_file, :libgit2), Cint,

base/libgit2/tag.jl

@@ -1,5 +1,10 @@
 # This file is a part of Julia. License is MIT: http://julialang.org/license
 
+"""
+    LibGit2.tag_list(repo::GitRepo) -> Vector{String}
+
+Get a list of all tags in the git repository `repo`.
+"""
 function tag_list(repo::GitRepo)
     sa_ref = Ref(StrArrayStruct())
     @check ccall((:git_tag_list, :libgit2), Cint,
@@ -9,11 +14,27 @@ function tag_list(repo::GitRepo)
     res
 end
 
+"""
+    LibGit2.tag_delete(repo::GitRepo, tag::AbstractString)
+
+Remove the git tag `tag` from the repository `repo`.
+"""
 function tag_delete(repo::GitRepo, tag::AbstractString)
     @check ccall((:git_tag_delete, :libgit2), Cint,
                   (Ptr{Void}, Cstring, ), repo.ptr, tag)
 end
 
+"""
+    LibGit2.tag_create(repo::GitRepo, tag::AbstractString, commit; kwargs...)
+
+Create a new git tag `tag` (e.g. `"v0.5"`) in the repository `repo`, at
+the commit `commit`.
+
+The keyword arguments are:
+  * `msg::AbstractString=""`: the message for the tag.
+  * `force::Bool=false`: if `true`, existing references will be overwritten.
+  * `sig::Signature=Signature(repo)`: the tagger's signature.
+"""
 function tag_create(repo::GitRepo, tag::AbstractString, commit::Union{AbstractString,AbstractGitHash};
                     msg::AbstractString = "",
                     force::Bool = false,
@@ -30,6 +51,11 @@ function tag_create(repo::GitRepo, tag::AbstractString, commit::Union{AbstractSt
     return oid_ptr[]
 end
 
+"""
+    LibGit2.name(tag::GitTag)
+
+The name of `tag` (e.g. `"v0.5"`).
+"""
 function name(tag::GitTag)
     str_ptr = ccall((:git_tag_name, :libgit2), Cstring, (Ptr{Void}, ), tag.ptr)
     str_ptr == C_NULL && throw(Error.GitError(Error.ERROR))