Merge pull request #23538 from JuliaLang/ksh/doccommit

Add docs for internal commit method

Author: kshyatt

base/libgit2/commit.jl

@@ -50,7 +50,6 @@ function Base.show(io::IO, c::GitCommit)
     print(io, "Git Commit:\nCommit Author: $authstr\nCommitter: $cmtrstr\nSHA: $(GitHash(c))\nMessage:\n$(message(c))")
 end
 
-""" Wrapper around `git_commit_create` """
 function commit(repo::GitRepo,
                 refname::AbstractString,
                 msg::AbstractString,
@@ -73,7 +72,25 @@ function commit(repo::GitRepo,
     return commit_id_ptr[]
 end
 
-"""Commit changes to repository"""
+"""
+    commit(repo::GitRepo, msg::AbstractString; kwargs...) -> GitHash
+
+Wrapper around [`git_commit_create`](https://libgit2.github.com/libgit2/#HEAD/group/commit/git_commit_create).
+Create a commit in the repository `repo`. `msg` is the commit message. Return the OID of the new commit.
+
+The keyword arguments are:
+  * `refname::AbstractString=Consts.HEAD_FILE`: if not NULL, the name of the reference to update to point to
+    the new commit. For example, `"HEAD"` will update the HEAD of the current branch. If the reference does
+    not yet exist, it will be created.
+  * `author::Signature = Signature(repo)` is a `Signature` containing information about the person who authored the commit.
+  * `committer::Signature = Signature(repo)` is a `Signature` containing information about the person who commited the commit to
+    the repository. Not necessarily the same as `author`, for instance if `author` emailed a patch to
+    `committer` who committed it.
+  * `tree_id::GitHash = GitHash()` is a git tree to use to create the commit, showing its ancestry and relationship with
+    any other history. `tree` must belong to `repo`.
+  * `parent_ids::Vector{GitHash}=GitHash[]` is a list of commits by [`GitHash`](@ref) to use as parent
+    commits for the new one, and may be empty. A commit might have multiple parents if it is a merge commit, for example.
+"""
 function commit(repo::GitRepo, msg::AbstractString;
                 refname::AbstractString=Consts.HEAD_FILE,
                 author::Signature = Signature(repo),