Merge pull request #1151 from arrbee/fix-diff-constructor-names

Fix diff constructor names

1 files changed, 93 insertions, 58 deletions

diff --git a/include/git2/diff.h b/include/git2/diff.h
index 49f781ddd..b26dd4214 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -139,7 +139,8 @@ typedef enum {
  * - `new_prefix` is the virtual "directory" to prefix to new file names
  *   in hunk headers (default "b")
  * - `pathspec` is an array of paths / fnmatch patterns to constrain diff
- * - `max_size` is a file size above which a blob will be marked as binary
+ * - `max_size` is a file size (in bytes) above which a blob will be marked
+ *   as binary automatically; pass a negative value to disable.
  */
 typedef struct {
 	unsigned int version;      /**< version for the struct */
@@ -148,8 +149,8 @@ typedef struct {
 	uint16_t interhunk_lines;  /**< defaults to 0 */
 	const char *old_prefix;    /**< defaults to "a" */
 	const char *new_prefix;    /**< defaults to "b" */
-	git_strarray pathspec;     /**< defaults to show all paths */
-	git_off_t max_size;        /**< defaults to 512mb */
+	git_strarray pathspec;     /**< defaults to include all paths */
+	git_off_t max_size;        /**< defaults to 512MB */
 } git_diff_options;
 
 #define GIT_DIFF_OPTIONS_VERSION 1
@@ -157,14 +158,19 @@ typedef struct {
 
 /**
  * The diff list object that contains all individual file deltas.
+ *
+ * This is an opaque structure which will be allocated by one of the diff
+ * generator functions below (such as `git_diff_tree_to_tree`).  You are
+ * responsible for releasing the object memory when done, using the
+ * `git_diff_list_free()` function.
  */
 typedef struct git_diff_list git_diff_list;
 
 /**
- * Flags that can be set for the file on side of a diff.
+ * Flags for the file object on each side of a diff.
  *
- * Most of the flags are just for internal consumption by libgit2,
- * but some of them may be interesting to external users.
+ * Note: most of these flags are just for **internal** consumption by
+ * libgit2, but some of them may be interesting to external users.
  */
 typedef enum {
 	GIT_DIFF_FILE_VALID_OID  = (1 << 0), /** `oid` value is known correct */
@@ -187,34 +193,38 @@ typedef enum {
  * DELETED pairs).
  */
 typedef enum {
-	GIT_DELTA_UNMODIFIED = 0,
-	GIT_DELTA_ADDED = 1,
-	GIT_DELTA_DELETED = 2,
-	GIT_DELTA_MODIFIED = 3,
-	GIT_DELTA_RENAMED = 4,
-	GIT_DELTA_COPIED = 5,
-	GIT_DELTA_IGNORED = 6,
-	GIT_DELTA_UNTRACKED = 7,
-	GIT_DELTA_TYPECHANGE = 8,
+	GIT_DELTA_UNMODIFIED = 0, /** no changes */
+	GIT_DELTA_ADDED = 1,	  /** entry does not exist in old version */
+	GIT_DELTA_DELETED = 2,	  /** entry does not exist in new version */
+	GIT_DELTA_MODIFIED = 3,   /** entry content changed between old and new */
+	GIT_DELTA_RENAMED = 4,    /** entry was renamed between old and new */
+	GIT_DELTA_COPIED = 5,     /** entry was copied from another old entry */
+	GIT_DELTA_IGNORED = 6,    /** entry is ignored item in workdir */
+	GIT_DELTA_UNTRACKED = 7,  /** entry is untracked item in workdir */
+	GIT_DELTA_TYPECHANGE = 8, /** type of entry changed between old and new */
 } git_delta_t;
 
 /**
- * Description of one side of a diff.
+ * Description of one side of a diff entry.
+ *
+ * Although this is called a "file", it may actually represent a file, a
+ * symbolic link, a submodule commit id, or even a tree (although that only
+ * if you are tracking type changes or ignored/untracked directories).
  *
- * The `oid` is the `git_oid` of the item.  If it represents an absent side
- * of a diff (e.g. the `old_file` of a `GIT_DELTA_ADDED` delta), then the
- * oid will be zeroes.
+ * The `oid` is the `git_oid` of the item.  If the entry represents an
+ * absent side of a diff (e.g. the `old_file` of a `GIT_DELTA_ADDED` delta),
+ * then the oid will be zeroes.
  *
- * `path` is the NUL-terminated path to the file relative to the working
+ * `path` is the NUL-terminated path to the entry relative to the working
  * directory of the repository.
  *
- * `size` is the size of the file in bytes.
+ * `size` is the size of the entry in bytes.
  *
  * `flags` is a combination of the `git_diff_file_flag_t` types, but those
  * are largely internal values.
  *
- * `mode` is, roughly, the stat() st_mode value for the item.  This will be
- * restricted to one of the `git_filemode_t` values.
+ * `mode` is, roughly, the stat() `st_mode` value for the item.  This will
+ * be restricted to one of the `git_filemode_t` values.
  */
 typedef struct {
 	git_oid oid;
@@ -225,17 +235,27 @@ typedef struct {
 } git_diff_file;
 
 /**
- * Description of changes to one file.
+ * Description of changes to one entry.
+ *
+ * When iterating over a diff list object, this will be passed to most
+ * callback functions and you can use the contents to understand exactly
+ * what has changed.
  *
- * When iterating over a diff list object, this will generally be passed to
- * most callback functions and you can use the contents to understand
- * exactly what has changed.
+ * The `old_file` repesents the "from" side of the diff and the `new_file`
+ * repesents to "to" side of the diff.  What those means depend on the
+ * function that was used to generate the diff and will be documented below.
+ * You can also use the `GIT_DIFF_REVERSE` flag to flip it around.
  *
- * Under some circumstances, not all fields will be filled in, but the code
- * generally tries to fill in as much as possible.  One example is that the
- * "binary" field will not actually look at file contents if you do not
- * pass in hunk and/or line callbacks to the diff foreach iteration function.
- * It will just use the git attributes for those files.
+ * Although the two sides of the delta are named "old_file" and "new_file",
+ * they actually may correspond to entries that represent a file, a symbolic
+ * link, a submodule commit id, or even a tree (if you are tracking type
+ * changes or ignored/untracked directories).
+ *
+ * Under some circumstances, in the name of efficiency, not all fields will
+ * be filled in, but we generally try to fill in as much as possible.  One
+ * example is that the "binary" field will not examine file contents if you
+ * do not pass in hunk and/or line callbacks to the diff foreach iteration
+ * function.  It will just use the git attributes for those files.
  */
 typedef struct {
 	git_diff_file old_file;
@@ -247,6 +267,10 @@ typedef struct {
 
 /**
  * When iterating over a diff, callback that will be made per file.
+ *
+ * @param delta A pointer to the delta data for the file
+ * @param progress Goes from 0 to 1 over the diff list
+ * @param payload User-specified pointer from foreach function
  */
 typedef int (*git_diff_file_cb)(
 	const git_diff_delta *delta,
@@ -257,10 +281,10 @@ typedef int (*git_diff_file_cb)(
  * Structure describing a hunk of a diff.
  */
 typedef struct {
-	int old_start;
-	int old_lines;
-	int new_start;
-	int new_lines;
+	int old_start; /** Starting line number in old_file */
+	int old_lines; /** Number of lines in old_file */
+	int new_start; /** Starting line number in new_file */
+	int new_lines; /** Number of lines in new_file */
 } git_diff_range;
 
 /**
@@ -308,12 +332,12 @@ typedef enum {
  * of lines of file and hunk headers.
  */
 typedef int (*git_diff_data_cb)(
-	const git_diff_delta *delta,
-	const git_diff_range *range,
-	char line_origin, /**< GIT_DIFF_LINE_... value from above */
-	const char *content,
-	size_t content_len,
-	void *payload);
+	const git_diff_delta *delta, /** delta that contains this data */
+	const git_diff_range *range, /** range of lines containing this data */
+	char line_origin,            /** git_diff_list_t value from above */
+	const char *content,         /** diff data - not NUL terminated */
+	size_t content_len,          /** number of bytes of diff data */
+	void *payload);              /** user reference data */
 
 /**
  * The diff patch is used to store all the text diffs for a delta.
@@ -381,9 +405,12 @@ typedef struct {
 GIT_EXTERN(void) git_diff_list_free(git_diff_list *diff);
 
 /**
- * Compute a difference between two tree objects.
+ * Create a diff list with the difference between two tree objects.
+ *
+ * This is equivalent to `git diff <old-tree> <new-tree>`
  *
- * This is equivalent to `git diff <treeish> <treeish>`
+ * 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.
  *
  * @param diff Output pointer to a git_diff_list pointer to be allocated.
  * @param repo The repository containing the trees.
@@ -399,18 +426,21 @@ GIT_EXTERN(int) git_diff_tree_to_tree(
 	const git_diff_options *opts); /**< can be NULL for defaults */
 
 /**
- * Compute a difference between a tree and the repository index.
+ * Create a diff list between a tree and repository index.
  *
  * This is equivalent to `git diff --cached <treeish>` or if you pass
  * the HEAD tree, then like `git diff --cached`.
  *
+ * The tree you pass will be used for the "old_file" side of the delta, and
+ * the index will be used for the "new_file" side of the delta.
+ *
  * @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 index The index to diff with; repo index used if NULL.
  * @param opts Structure with options to influence diff or NULL for defaults.
  */
-GIT_EXTERN(int) git_diff_index_to_tree(
+GIT_EXTERN(int) git_diff_tree_to_index(
 	git_diff_list **diff,
 	git_repository *repo,
 	git_tree *old_tree,
@@ -418,40 +448,45 @@ GIT_EXTERN(int) git_diff_index_to_tree(
 	const git_diff_options *opts); /**< can be NULL for defaults */
 
 /**
- * Compute a difference between the working directory and the repository index.
+ * Create a diff list between the repository index and the workdir directory.
  *
  * This matches the `git diff` command.  See the note below on
- * `git_diff_workdir_to_tree` for a discussion of the difference between
+ * `git_diff_tree_to_workdir` for a discussion of the difference between
  * `git diff` and `git diff HEAD` and how to emulate a `git diff <treeish>`
  * using libgit2.
  *
+ * The index will be used for the "old_file" side of the delta, and the
+ * working directory will be used for the "new_file" side of the delta.
+ *
  * @param diff Output pointer to a git_diff_list pointer to be allocated.
  * @param repo The repository.
  * @param index The index to diff from; repo index used if NULL.
  * @param opts Structure with options to influence diff or NULL for defaults.
  */
-GIT_EXTERN(int) git_diff_workdir_to_index(
+GIT_EXTERN(int) git_diff_index_to_workdir(
 	git_diff_list **diff,
 	git_repository *repo,
 	git_index *index,
 	const git_diff_options *opts); /**< can be NULL for defaults */
 
 /**
- * Compute a difference between the working directory and a tree.
+ * Create a diff list between a tree and the working directory.
+ *
+ * The tree you provide will be used for the "old_file" side of the delta,
+ * and the working directory will be used for the "new_file" side.
  *
- * This is *NOT* the same as `git diff <treeish>`.  Running `git diff HEAD`
- * or the like actually uses information from the index, along with the tree
- * and workdir dir info.
+ * Please note: this is *NOT* the same as `git diff <treeish>`.  Running
+ * `git diff HEAD` or the like actually uses information from the index,
+ * along with the tree and working directory info.
  *
  * This function returns strictly the differences between the tree and the
  * files contained in the working directory, regardless of the state of
  * files in the index.  It may come as a surprise, but there is no direct
  * equivalent in core git.
  *
- * To emulate `git diff <treeish>`, you should call both
- * `git_diff_index_to_tree` and `git_diff_workdir_to_index`, then call
- * `git_diff_merge` on the results.  That will yield a `git_diff_list` that
- * matches the git output.
+ * To emulate `git diff <treeish>`, call both `git_diff_tree_to_index` and
+ * `git_diff_index_to_workdir`, then call `git_diff_merge` on the results.
+ * That will yield a `git_diff_list` that matches the git output.
  *
  * If this seems confusing, take the case of a file with a staged deletion
  * where the file has then been put back into the working dir and modified.
@@ -463,7 +498,7 @@ GIT_EXTERN(int) git_diff_workdir_to_index(
  * @param old_tree A git_tree object to diff from.
  * @param opts Structure with options to influence diff or NULL for defaults.
  */
-GIT_EXTERN(int) git_diff_workdir_to_tree(
+GIT_EXTERN(int) git_diff_tree_to_workdir(
 	git_diff_list **diff,
 	git_repository *repo,
 	git_tree *old_tree,