Merge pull request #3888 from libgit2/ethomson/doc_diff_from_buffer

diff: document `git_diff_from_buffer`

CHANGELOG.md

@@ -46,6 +46,9 @@ v0.24 + 1
       `git_repository_open_ext` with this flag will error out if either
       `$GIT_WORK_TREE` or `$GIT_COMMON_DIR` is set.
 
+* `git_diff_from_buffer` can create a `git_diff` object from the contents
+  of a git-style patch file.
+
 ### API removals
 
 * `git_blob_create_fromchunks()` has been removed in favour of

include/git2/diff.h

@@ -1189,6 +1189,25 @@ GIT_EXTERN(int) git_diff_buffers(
 	git_diff_line_cb line_cb,
 	void *payload);
 
+/**
+ * Read the contents of a git patch file into a `git_diff` object.
+ *
+ * The diff object produced is similar to the one that would be
+ * produced if you actually produced it computationally by comparing
+ * two trees, however there may be subtle differences.  For example,
+ * a patch file likely contains abbreviated object IDs, so the
+ * object IDs in a `git_diff_delta` produced by this function will
+ * also be abbreviated.
+ *
+ * This function will only read patch files created by a git
+ * implementation, it will not read unified diffs produced by
+ * the `diff` program, nor any other types of patch files.
+ *
+ * @param out A pointer to a git_diff pointer that will be allocated.
+ * @param content The contents of a patch file
+ * @param content_len The length of the patch file contents
+ * @return 0 or an error code
+ */
 GIT_EXTERN(int) git_diff_from_buffer(
 	git_diff **out,
 	const char *content,