merge-ort: add function grouping comments

Commit b658536f59 ("merge-ort: add some high-level algorithm structure",
2020-10-27) added high-level structure of the ort merge algorithm.  As
we have added more and more functions, that high-level structure has
been slightly obscured.  Since functions are still grouped according to
this high-level structure, add comments denoting sections where all the
functions are specifically tied to a piece of the high-level structure.

This function groupings include a few sub-divisions of the original
high-level structure, including some sub-divisions that are yet to be
submitted.  Each has (or will have) several functions all serving as
helpers to one or two main functions for each section.

As an added bonus, the comments will serve to provide a small textual
separation between nearby sections and allow the next three patch series
to be submitted independently and merge cleanly.

Signed-off-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/merge-ort.c b/merge-ort.c
index ae855a4ae531069b01d8789e276d4c1cb4b895e8..8a144fbe292679c9f97257f3365cf629cabde725 100644 (file)
--- a/merge-ort.c
+++ b/merge-ort.c
@@ -210,6 +210,8 @@ struct conflict_info {
        unsigned match_mask:3;
 };
 
+/*** Function Grouping: various utility functions ***/
+
 /*
  * For the next three macros, see warning for conflict_info.merged.
  *
@@ -290,6 +292,8 @@ static int err(struct merge_options *opt, const char *err, ...)
        return -1;
 }
 
+/*** Function Grouping: functions related to collect_merge_info() ***/
+
 static void setup_path_info(struct merge_options *opt,
                            struct string_list_item *result,
                            const char *current_dir_name,
@@ -544,6 +548,15 @@ static int collect_merge_info(struct merge_options *opt,
        return ret;
 }
 
+/*** Function Grouping: functions related to threeway content merges ***/
+
+/*** Function Grouping: functions related to detect_and_process_renames(), ***
+ *** which are split into directory and regular rename detection sections. ***/
+
+/*** Function Grouping: functions related to directory rename detection ***/
+
+/*** Function Grouping: functions related to regular rename detection ***/
+
 static int detect_and_process_renames(struct merge_options *opt,
                                      struct tree *merge_base,
                                      struct tree *side1,
@@ -561,6 +574,8 @@ static int detect_and_process_renames(struct merge_options *opt,
        return clean;
 }
 
+/*** Function Grouping: functions related to process_entries() ***/
+
 static int string_list_df_name_compare(const char *one, const char *two)
 {
        int onelen = strlen(one);
@@ -1039,6 +1054,8 @@ static void process_entries(struct merge_options *opt,
        string_list_clear(&dir_metadata.offsets, 0);
 }
 
+/*** Function Grouping: functions related to merge_switch_to_result() ***/
+
 static int checkout(struct merge_options *opt,
                    struct tree *prev,
                    struct tree *next)
@@ -1226,6 +1243,8 @@ void merge_finalize(struct merge_options *opt,
        FREE_AND_NULL(opti);
 }
 
+/*** Function Grouping: helper functions for merge_incore_*() ***/
+
 static void merge_start(struct merge_options *opt, struct merge_result *result)
 {
        /* Sanity checks on opt */
@@ -1276,6 +1295,8 @@ static void merge_start(struct merge_options *opt, struct merge_result *result)
        string_list_init(&opt->priv->paths_to_free, 0);
 }
 
+/*** Function Grouping: merge_incore_*() and their internal variants ***/
+
 /*
  * Originally from merge_trees_internal(); heavily adapted, though.
  */