diff: document `git_diff_from_buffer`ethomson/doc_diff_from_buffer

1 files changed, 19 insertions, 0 deletions

diff --git a/include/git2/diff.h b/include/git2/diff.h
index ac5db711c..c5e463fe3 100644
--- a/include/git2/diff.h
+++ b/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,