remove a TODO that turned out to be unnecessary.

After all, stopping the merge when there is any conflict is highly relevant.

README.md

@@ -46,7 +46,7 @@ What follows is a high-level list of features and those which are planned:
 * [x] blob-diff
 * [ ] merge
     - [x] blobs
-    - [ ] trees
+    - [x] trees
     - [ ] commits
 * [ ] rebase
 * [ ] commit

gix-merge/src/lib.rs

@@ -1,3 +1,8 @@
+//! Provide facilities to merge *blobs*, *trees* and *commits*.
+//!
+//! * [blob-merges](blob) look at file content.
+//! * [tree-merges](tree) look at trees and merge them structurally, triggering blob-merges as needed.
+//! * [commit-merges](commit) are like tree merges, but compute or create the merge-base on the fly.
 #![deny(rust_2018_idioms)]
 #![forbid(unsafe_code)]
 

gix-merge/src/tree/mod.rs

@@ -29,7 +29,7 @@ pub enum Error {
 /// The outcome produced by [`tree()`](crate::tree()).
 #[derive(Clone)]
 pub struct Outcome<'a> {
-    /// The ready-made (but unwritten) which is the *base* tree, including all non-conflicting changes, and the changes that had
+    /// The ready-made (but unwritten) *base* tree, including all non-conflicting changes, and the changes that had
     /// conflicts which could be resolved automatically.
     ///
     /// This means, if all of their changes were conflicting, this will be equivalent to the *base* tree.
@@ -70,7 +70,7 @@ impl Outcome<'_> {
 #[derive(Debug, Clone)]
 pub struct Conflict {
     /// A record on how the conflict resolution succeeded with `Ok(_)` or failed with `Err(_)`.
-    /// In case of `Err(_)`, no write
+    /// Note that in case of `Err(_)`, edits may still have been made to the tree to aid resolution.
     /// On failure, one can examine `ours` and `theirs` to potentially find a custom solution.
     /// Note that the descriptions of resolutions or resolution failures may be swapped compared
     /// to the actual changes. This is due to changes like `modification|deletion` being treated the
@@ -81,13 +81,17 @@ pub struct Conflict {
     pub ours: Change,
     /// The change representing *their* side.
     pub theirs: Change,
+    /// Determine how to interpret the `ours` and `theirs` fields. This is used to implement [`Self::changes_in_resolution()`]
+    /// and [`Self::into_parts_by_resolution()`].
     map: ConflictMapping,
 }
 
-/// A utility to help define which side is what.
+/// A utility to help define which side is what in the [`Conflict`] type.
 #[derive(Debug, Clone, Copy)]
 enum ConflictMapping {
+    /// The sides are as described in the field documentation, i.e. `ours` is `ours`.
     Original,
+    /// The sides are the opposite of the field documentation. i.e. `ours` is `theirs` and `theirs` is `ours`.
     Swapped,
 }
 
@@ -236,11 +240,8 @@ pub struct Options {
     /// The context to use when invoking merge-drivers.
     pub blob_merge_command_ctx: gix_command::Context,
     /// If `Some(what-is-unresolved)`, the first unresolved conflict will cause the entire merge to stop.
-    /// This is useful to see if there is any conflict, without performing the whole operation.
-    // TODO: Maybe remove this if the cost of figuring out conflicts is so low - after all, the data structures
-    //       and initial diff is the expensive thing right now, which are always done upfront.
-    //       However, this could change once we know do everything during the traversal, which probably doesn't work
-    //       without caching stuff and is too complicated to actually do.
+    /// This is useful to see if there is any conflict, without performing the whole operation, something
+    /// that can be very relevant during merges that would cause a lot of blob-diffs.
     pub fail_on_conflict: Option<UnresolvedConflict>,
     /// This value also affects the size of merge-conflict markers, to allow differentiating
     /// merge conflicts on each level, for any value greater than 0, with values `N` causing `N*2`

gix/src/repository/merge.rs

@@ -111,6 +111,11 @@ impl Repository {
     /// `labels` are typically chosen to identify the refs or names for `our_tree` and `their_tree` and `ancestor_tree` respectively.
     ///
     /// `options` should be initialized with [`tree_merge_options()`](Self::tree_merge_options()).
+    ///
+    /// ### Performance
+    ///
+    /// It's highly recommended to [set an object cache](crate::Repository::compute_object_cache_size_for_tree_diffs)
+    /// to avoid extracting the same object multiple times.
     // TODO: Use `crate::merge::Options` here and add niceties such as setting the resolution strategy.
     pub fn merge_trees(
         &self,