Improve documentation for merging

1 files changed, 127 insertions, 33 deletions

diff --git a/include/git2/merge.h b/include/git2/merge.h
index 3ef27e3c7..b45d0fd5e 100644
--- a/include/git2/merge.h
+++ b/include/git2/merge.h
@@ -27,24 +27,47 @@ GIT_BEGIN_DECL
  * passed in via the `flags` value in the `git_merge_tree_opts`.
  */
 typedef enum {
-	/** Detect renames */
+	/**
+	 * Detect renames that occur between the common ancestor and the "ours"
+	 * side or the common ancestor and the "theirs" side.  This will enable
+	 * the ability to merge between a modified and renamed file.
+	 */
 	GIT_MERGE_TREE_FIND_RENAMES = (1 << 0),
 } git_merge_tree_flag_t;
 
 /**
- * Merge file options for `git_merge_trees_opts`.
+ * Merge file favor options for `git_merge_trees_opts` instruct the file-level
+ * merging functionality how to deal with conflicting regions of the files.
  */
 typedef enum {
-	/* Produce a conflict in a file when two similar regions are changed. */
+	/**
+	 * When a region of a file is changed in both branches, a conflict
+	 * will be recorded in the index so that `git_checkout` can produce
+	 * a merge file with conflict markers in the working directory.
+	 * This is the default.
+	 */
 	GIT_MERGE_FILE_FAVOR_NORMAL = 0,
 
-	/* Produce a file containing the "ours" side of conflicting regions. */
+	/**
+	 * When a region of a file is changed in both branches, the file
+	 * created in the index will contain the "ours" side of any conflicting
+	 * region.  The index will not record a conflict.
+	 */
 	GIT_MERGE_FILE_FAVOR_OURS = 1,
 
-	/* Produce a file containing the "theirs" side of conflicting regions. */
+	/**
+	 * When a region of a file is changed in both branches, the file
+	 * created in the index will contain the "theirs" side of any conflicting
+	 * region.  The index will not record a conflict.
+	 */
 	GIT_MERGE_FILE_FAVOR_THEIRS = 2,
 
-	/* Produce a file blending the sides in a union of conflicting regions */
+	/**
+	 * When a region of a file is changed in both branches, the file
+	 * created in the index will contain each unique line from each side,
+	 * which has the result of combining both files.  The index will not
+	 * record a conflict.
+	 */
 	GIT_MERGE_FILE_FAVOR_UNION = 3,
 } git_merge_file_favor_t;
 
@@ -53,18 +76,28 @@ typedef struct {
 	unsigned int version;
 	git_merge_tree_flag_t flags;
 
-	/** Similarity to consider a file renamed (default 50) */
+	/**
+	 * Similarity to consider a file renamed (default 50).  If
+	 * `GIT_MERGE_TREE_FIND_RENAMES` is enabled, added files will be compared
+	 * with deleted files to determine their similarity.  Files that are
+	 * more similar than the rename threshold (percentage-wise) will be
+	 * treated as a rename.
+	 */
 	unsigned int rename_threshold;
 
-	/** Maximum similarity sources to examine (overrides the
-	 * `merge.renameLimit` config) (default 200)
+	/**
+	 * Maximum similarity sources to examine for renames (default 200).
+	 * If the number of rename candidates (add / delete pairs) is greater
+	 * than this value, inexact rename detection is aborted.
+	 *
+	 * This setting overrides the `merge.renameLimit` configuration value.
 	 */
 	unsigned int target_limit;
 
 	/** Pluggable similarity metric; pass NULL to use internal metric */
 	git_diff_similarity_metric *metric;
 
-	/** Flags for automerging content. */
+	/** Flags for handling conflicting content. */
 	git_merge_file_favor_t file_favor;
 } git_merge_tree_opts;
 
@@ -74,20 +107,37 @@ typedef struct {
 
 /**
  * Option flags for `git_merge`.
- *
- * GIT_MERGE_NO_FASTFORWARD - Do not fast-forward.
  */
 typedef enum {
-	GIT_MERGE_NO_FASTFORWARD      = 1,
-	GIT_MERGE_FASTFORWARD_ONLY    = 2,
+	/**
+	 * The default behavior is to allow fast-forwards, returning
+	 * immediately with the commit ID to fast-forward to.
+	 */
+	GIT_MERGE_DEFAULT = 0,
+
+	/**
+	 * Do not fast-forward; perform a merge and prepare a merge result even
+	 * if the inputs are eligible for fast-forwarding.
+	 */
+	GIT_MERGE_NO_FASTFORWARD = 1,
+
+	/**
+	 * Ensure that the inputs are eligible for fast-forwarding, error if
+	 * a merge needs to be performed.
+	 */
+	GIT_MERGE_FASTFORWARD_ONLY = 2,
 } git_merge_flags_t;
 
 typedef struct {
 	unsigned int version;
 
+	/** Options for handling the commit-level merge. */
 	git_merge_flags_t merge_flags;
+
+	/** Options for handling the merges of individual files. */
 	git_merge_tree_opts merge_tree_opts;
 
+	/** Options for writing the merge result to the working directory. */
 	git_checkout_opts checkout_opts;
 } git_merge_opts;
 
@@ -102,7 +152,7 @@ typedef struct {
  * @param repo the repository where the commits exist
  * @param one one of the commits
  * @param two the other commit
- * @return Zero on success; GIT_ENOTFOUND or -1 on failure.
+ * @return 0 on success, GIT_ENOTFOUND if not found or error code
  */
 GIT_EXTERN(int) git_merge_base(
 	git_oid *out,
@@ -117,7 +167,7 @@ GIT_EXTERN(int) git_merge_base(
  * @param repo the repository where the commits exist
  * @param length The number of commits in the provided `input_array`
  * @param input_array oids of the commits
- * @return Zero on success; GIT_ENOTFOUND or -1 on failure.
+ * @return 0 on success, GIT_ENOTFOUND if not found or error code
  */
 GIT_EXTERN(int) git_merge_base_many(
 	git_oid *out,
@@ -126,12 +176,13 @@ GIT_EXTERN(int) git_merge_base_many(
 	const git_oid input_array[]);
 
 /**
- * Creates a `git_merge_head` from the given reference
+ * Creates a `git_merge_head` from the given reference.  The resulting
+ * git_merge_head must be freed with `git_merge_head_free`.
  *
  * @param out pointer to store the git_merge_head result in
  * @param repo repository that contains the given reference
  * @param ref reference to use as a merge input
- * @return zero on success, -1 on failure.
+ * @return 0 on success or error code
  */
 GIT_EXTERN(int) git_merge_head_from_ref(
 	git_merge_head **out,
@@ -139,14 +190,15 @@ GIT_EXTERN(int) git_merge_head_from_ref(
 	git_reference *ref);
 
 /**
- * Creates a `git_merge_head` from the given fetch head data
+ * Creates a `git_merge_head` from the given fetch head data.  The resulting
+ * git_merge_head must be freed with `git_merge_head_free`.
  *
  * @param out pointer to store the git_merge_head result in
  * @param repo repository that contains the given commit
  * @param branch_name name of the (remote) branch
  * @param remote_url url of the remote
  * @param oid the commit object id to use as a merge input
- * @return zero on success, -1 on failure.
+ * @return 0 on success or error code
  */
 GIT_EXTERN(int) git_merge_head_from_fetchhead(
 	git_merge_head **out,
@@ -156,12 +208,13 @@ GIT_EXTERN(int) git_merge_head_from_fetchhead(
 	const git_oid *oid);
 
 /**
- * Creates a `git_merge_head` from the given commit id
+ * Creates a `git_merge_head` from the given commit id.  The resulting
+ * git_merge_head must be freed with `git_merge_head_free`.
  *
  * @param out pointer to store the git_merge_head result in
  * @param repo repository that contains the given commit
  * @param id the commit object id to use as a merge input
- * @return zero on success, -1 on failure.
+ * @return 0 on success or error code
  */
 GIT_EXTERN(int) git_merge_head_from_id(
 	git_merge_head **out,
@@ -169,7 +222,7 @@ GIT_EXTERN(int) git_merge_head_from_id(
 	const git_oid *id);
 
 /**
- * Frees a `git_merge_head`
+ * Frees a `git_merge_head`.
  *
  * @param head merge head to free
  */
@@ -178,7 +231,9 @@ GIT_EXTERN(void) git_merge_head_free(
 
 /**
  * Merge two trees, producing a `git_index` that reflects the result of
- * the merge.
+ * the merge.  The index may be written as-is to the working directory
+ * or checked out.  If the index is to be converted to a tree, the caller
+ * should resolve any conflicts that arose as part of the merge.
  *
  * The returned index must be freed explicitly with `git_index_free`.
  *
@@ -188,7 +243,7 @@ GIT_EXTERN(void) git_merge_head_free(
  * @param our_tree the tree that reflects the destination tree
  * @param their_tree the tree to merge in to `our_tree`
  * @param opts the merge tree options (or null for defaults)
- * @return zero on success, -1 on failure.
+ * @return 0 on success or error code
  */
 GIT_EXTERN(int) git_merge_trees(
 	git_index **out,
@@ -200,7 +255,9 @@ GIT_EXTERN(int) git_merge_trees(
 
 /**
  * Merge two commits, producing a `git_index` that reflects the result of
- * the merge.
+ * the merge.  The index may be written as-is to the working directory
+ * or checked out.  If the index is to be converted to a tree, the caller
+ * should resolve any conflicts that arose as part of the merge.
  *
  * The returned index must be freed explicitly with `git_index_free`.
  *
@@ -209,7 +266,7 @@ GIT_EXTERN(int) git_merge_trees(
  * @param our_commit the commit that reflects the destination tree
  * @param their_commit the commit to merge in to `our_commit`
  * @param opts the merge tree options (or null for defaults)
- * @return zero on success, -1 on failure.
+ * @return 0 on success or error code
  */
 GIT_EXTERN(int) git_merge_commits(
 	git_index **out,
@@ -219,13 +276,32 @@ GIT_EXTERN(int) git_merge_commits(
 	const git_merge_tree_opts *opts);
 
 /**
- * Merges the given commits into HEAD, producing a new commit.
+ * Merges the given commit(s) into HEAD and either returns immediately
+ * if there was no merge to perform (the specified commits have already
+ * been merged or would produce a fast-forward) or performs the merge
+ * and writes the results into the working directory.
+ *
+ * Callers should inspect the `git_merge_result`:
+ *
+ * If `git_merge_result_is_uptodate` is true, there is no work to perform.
+ *
+ * If `git_merge_result_is_fastforward` is true, the caller should update
+ * any necessary references to the commit ID returned by
+ * `git_merge_result_fastforward_id` and check that out in order to complete
+ * the fast-forward.
+ * 
+ * Otherwise, callers should inspect the resulting index, resolve any
+ * conflicts and prepare a commit.
+ *
+ * The resultant `git_merge_result` should be free with
+ * `git_merge_result_free`.
  *
  * @param out the results of the merge
  * @param repo the repository to merge
  * @param merge_heads the heads to merge into
  * @param merge_heads_len the number of heads to merge
- * @param flags merge flags
+ * @param opts merge options
+ * @return 0 on success or error code
  */
 GIT_EXTERN(int) git_merge(
 	git_merge_result **out,
@@ -235,24 +311,42 @@ GIT_EXTERN(int) git_merge(
 	const git_merge_opts *opts);
 
 /**
- * Returns true if a merge is up-to-date (we were asked to merge the target
- * into itself.)
+ * Returns true if a merge is "up-to-date", meaning that the commit(s) 
+ * that were provided to `git_merge` are already included in `HEAD`
+ * and there is no work to do.
+ *
+ * @return true if the merge is up-to-date, false otherwise
  */
 GIT_EXTERN(int) git_merge_result_is_uptodate(git_merge_result *merge_result);
 
 /**
- * Returns true if a merge is eligible for fastforward
+ * Returns true if a merge is eligible to be "fast-forwarded", meaning that
+ * the commit that was provided to `git_merge` need not be merged, it can
+ * simply be checked out, because the current `HEAD` is the merge base of
+ * itself and the given commit.  To perform the fast-forward, the caller
+ * should check out the results of `git_merge_result_fastforward_id`.
+ * 
+ * This will never be true if `GIT_MERGE_NO_FASTFORWARD` is supplied as
+ * a merge option.
+ *
+ * @return true if the merge is fast-forwardable, false otherwise
  */
 GIT_EXTERN(int) git_merge_result_is_fastforward(git_merge_result *merge_result);
 
 /**
  * Gets the fast-forward OID if the merge was a fastforward.
  *
- * @param out the OID of the fast-forward
+ * @param out pointer to populate with the OID of the fast-forward
  * @param merge_result the results of the merge
+ * @return 0 on success or error code
  */
 GIT_EXTERN(int) git_merge_result_fastforward_id(git_oid *out, git_merge_result *merge_result);
 
+/**
+ * Frees a `git_merge_result`.
+ *
+ * @param result merge result to free
+ */
 GIT_EXTERN(void) git_merge_result_free(git_merge_result *merge_result);
 
 /** @} */