From d63eec6946341e5efa0514bbf2904db2ded2a294 Mon Sep 17 00:00:00 2001 From: Russell Belfer Date: Tue, 7 May 2013 04:44:08 -0700 Subject: [PATCH] Improve diff function docs --- include/git2/diff.h | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/include/git2/diff.h b/include/git2/diff.h index e10b65f7b..1feddd7a2 100644 --- a/include/git2/diff.h +++ b/include/git2/diff.h @@ -490,6 +490,8 @@ typedef struct { /** * Deallocate a diff list. + * + * @param diff The previously created diff list; cannot be used after free. */ GIT_EXTERN(void) git_diff_list_free(git_diff_list *diff); @@ -499,12 +501,14 @@ GIT_EXTERN(void) git_diff_list_free(git_diff_list *diff); * This is equivalent to `git diff ` * * The first tree will be used for the "old_file" side of the delta and the - * second tree will be used for the "new_file" side of the delta. + * second tree will be used for the "new_file" side of the delta. You can + * pass NULL to indicate an empty tree, although it is an error to pass + * NULL for both the `old_tree` and `new_tree`. * * @param diff Output pointer to a git_diff_list pointer to be allocated. * @param repo The repository containing the trees. - * @param old_tree A git_tree object to diff from. - * @param new_tree A git_tree object to diff to. + * @param old_tree A git_tree object to diff from, or NULL for empty tree. + * @param new_tree A git_tree object to diff to, or NULL for empty tree. * @param opts Structure with options to influence diff or NULL for defaults. */ GIT_EXTERN(int) git_diff_tree_to_tree( @@ -525,7 +529,7 @@ GIT_EXTERN(int) git_diff_tree_to_tree( * * @param diff Output pointer to a git_diff_list pointer to be allocated. * @param repo The repository containing the tree and index. - * @param old_tree A git_tree object to diff from. + * @param old_tree A git_tree object to diff from, or NULL for empty tree. * @param index The index to diff with; repo index used if NULL. * @param opts Structure with options to influence diff or NULL for defaults. */ @@ -584,7 +588,7 @@ GIT_EXTERN(int) git_diff_index_to_workdir( * * @param diff A pointer to a git_diff_list pointer that will be allocated. * @param repo The repository containing the tree. - * @param old_tree A git_tree object to diff from. + * @param old_tree A git_tree object to diff from, or NULL for empty tree. * @param opts Structure with options to influence diff or NULL for defaults. */ GIT_EXTERN(int) git_diff_tree_to_workdir( @@ -928,7 +932,14 @@ GIT_EXTERN(int) git_diff_patch_to_str( * to 1 and no call to the hunk_cb nor line_cb will be made (unless you pass * `GIT_DIFF_FORCE_TEXT` of course). * - * @return 0 on success, GIT_EUSER on non-zero callback, or error code + * @param old_blob Blob for old side of diff, or NULL for empty blob + * @param new_blob Blob for new side of diff, or NULL for empty blob + * @param options Options for diff, or NULL for default options + * @param file_cb Callback for "file"; made once if there is a diff; can be NULL + * @param hunk_cb Callback for each hunk in diff; can be NULL + * @param line_cb Callback for each line in diff; can be NULL + * @param payload Payload passed to each callback function + * @return 0 on success, GIT_EUSER on non-zero callback return, or error code */ GIT_EXTERN(int) git_diff_blobs( const git_blob *old_blob, @@ -951,7 +962,15 @@ GIT_EXTERN(int) git_diff_blobs( * entire content of the buffer added). Passing NULL to the buffer will do * the reverse, with GIT_DELTA_REMOVED and blob content removed. * - * @return 0 on success, GIT_EUSER on non-zero callback, or error code + * @param old_blob Blob for old side of diff, or NULL for empty blob + * @param buffer Raw data for new side of diff + * @param buffer_len Length of raw data for new side of diff + * @param options Options for diff, or NULL for default options + * @param file_cb Callback for "file"; made once if there is a diff; can be NULL + * @param hunk_cb Callback for each hunk in diff; can be NULL + * @param line_cb Callback for each line in diff; can be NULL + * @param payload Payload passed to each callback function + * @return 0 on success, GIT_EUSER on non-zero callback return, or error code */ GIT_EXTERN(int) git_diff_blob_to_buffer( const git_blob *old_blob,