Add docs for the diff.jl methods

base/libgit2/diff.jl

@@ -11,7 +11,18 @@ function Base.unsafe_convert(::Type{Ptr{DiffOptionsStruct}}, rr::Tuple{Ref{DiffO
     Base.unsafe_convert(Ptr{DiffOptionsStruct}, first(rr))
 end
 
+"""
+    diff_tree(repo::GitRepo, tree::GitTree, pathspecs::AbstractString=""; cached::Bool=false)
 
+Generate a [`GitDiff`](@ref) between `tree` (which will be used for the "old"
+side of the [`DiffDelta`](@ref)) and `repo` (which will be used for the "new" side).
+If `repo` is `cached`, calls [`git_diff_tree_to_index`](https://libgit2.github.com/libgit2/#HEAD/group/diff/git_diff_tree_to_index).
+The `cached` version is generally used to examine the diff for staged changes from one
+commit to the next. If `cached` is `false`, calls
+[`git_diff_tree_to_workdir_with_index`](https://libgit2.github.com/libgit2/#HEAD/group/diff/git_diff_tree_to_workdir_with_index).
+This compares the current working directory against the [`GitIndex`](@ref) and can,
+for example, be used to examine the changes in staged files before a commit.
+"""
 function diff_tree(repo::GitRepo, tree::GitTree, pathspecs::AbstractString=""; cached::Bool=false)
     diff_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
     if cached
@@ -26,6 +37,16 @@ function diff_tree(repo::GitRepo, tree::GitTree, pathspecs::AbstractString=""; c
     return GitDiff(repo, diff_ptr_ptr[])
 end
 
+"""
+    diff_tree(repo::GitRepo, oldtree::GitTree, newtree::GitTree)
+
+Generate a [`GitDiff`](@ref) between `oldtree` (which will be used for the "old"
+side of the [`DiffDelta`](@ref)) and `newtree` (which will be used for the "new"
+side of the `DiffDelta`). Equivalent to [`git_diff_tree_to_tree`](https://libgit2.github.com/libgit2/#HEAD/group/diff/git_diff_tree_to_tree).
+This can be used to generate a diff between two commits. For instance, it could
+be used to compare a commit made 2 months ago with the current latest commit, or
+to compare a commit on another branch with the current latest commit on `master`.
+"""
 function diff_tree(repo::GitRepo, oldtree::GitTree, newtree::GitTree)
     diff_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
     @check ccall((:git_diff_tree_to_tree, :libgit2), Cint,
@@ -34,6 +55,13 @@ function diff_tree(repo::GitRepo, oldtree::GitTree, newtree::GitTree)
     return GitDiff(repo, diff_ptr_ptr[])
 end
 
+"""
+    GitDiffStats(diff::GitDiff)
+
+Get the diff statistics from the [`GitDiff`](@ref) `diff`. This object records a
+summary of changes made across the `diff`. In particular, it records how many
+files were changed, how many insertions were made, and how many deletions were made.
+"""
 function GitDiffStats(diff::GitDiff)
     diff_stat_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
     @check ccall((:git_diff_get_stats, :libgit2), Cint,
@@ -42,14 +70,38 @@ function GitDiffStats(diff::GitDiff)
     return GitDiffStats(diff.owner, diff_stat_ptr_ptr[])
 end
 
+"""
+    files_changed(diff_stat::GitDiffStats) -> Csize_t
+
+Return how many files were changed (added/modified/deleted) in the [`GitDiff`](@ref)
+summarized by `diff_stat`. The result may vary depending on the [`DiffOptionsStruct`](@ref)
+used to generate the parent `GitDiff` of `diff_stat` (for instance, whether ignored files
+are to be included or not).
+"""
 function files_changed(diff_stat::GitDiffStats)
     return ccall((:git_diff_stats_files_changed, :libgit2), Csize_t, (Ptr{Void},), diff_stat.ptr)
 end
 
+"""
+    insertions(diff_stat::GitDiffStats) -> Csize_t
+
+Return the total number of insertions (lines added) in the [`GitDiff`](@ref)
+summarized by `diff_stat`. The result may vary depending on the [`DiffOptionsStruct`](@ref)
+used to generate the parent `GitDiff` of `diff_stat` (for instance, whether ignored files
+are to be included or not).
+"""
 function insertions(diff_stat::GitDiffStats)
     return ccall((:git_diff_stats_insertions, :libgit2), Csize_t, (Ptr{Void},), diff_stat.ptr)
 end
 
+"""
+    deletions(diff_stat::GitDiffStats) -> Csize_t
+
+Return the total number of deletions (lines removed) in the [`GitDiff`](@ref)
+summarized by `diff_stat`. The result may vary depending on the [`DiffOptionsStruct`](@ref)
+used to generate the parent `GitDiff` of `diff_stat` (for instance, whether ignored files
+are to be included or not).
+"""
 function deletions(diff_stat::GitDiffStats)
     return ccall((:git_diff_stats_deletions, :libgit2), Csize_t, (Ptr{Void},), diff_stat.ptr)
 end