Improve diff function docs

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 <old-tree> <new-tree>`
  *
  * 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,