Elijah Newren <newren@xxxxxxxxx> writes:
> If I have to walk through the debugger and inspect the values found in
> here in order to figure out their meaning, despite having known these
> things inside and out some years back, then they probably need a comment
> for the casual reader to explain their purpose.
>
> Signed-off-by: Elijah Newren <newren@xxxxxxxxx>
> ---
> merge-recursive.c | 22 ++++++++++++++++++++++
> 1 file changed, 22 insertions(+)
>
> diff --git a/merge-recursive.c b/merge-recursive.c
> index 52521faf09..3526c8d0b8 100644
> --- a/merge-recursive.c
> +++ b/merge-recursive.c
> @@ -513,6 +513,28 @@ static void record_df_conflict_files(struct merge_options *o,
>
> struct rename {
> struct diff_filepair *pair;
> + /*
> + * Because I keep forgetting every few years what src_entry and
> + * dst_entry are and have to walk through a debugger and puzzle
> + * through it to remind myself...
Very much appreciated. I recall having trouble reasoning about
them myself, too (even though I admit I wasn't involved in the
implementation of this part very much and know this code a lot less
intimately than you do in the first place).
> + *
> + * If 'before' is renamed to 'after' then src_entry will contain
> + * the versions of 'before' from the merge_base, HEAD, and MERGE in
> + * stages 1, 2, and 3; dst_entry will contain the versions of
> + * 'after' from the merge_base, HEAD, and MERGE in stages 1, 2, and
> + * 3. Thus, we have a total of six modes and oids, though some
> + * will be null. (Stage 0 is ignored; we're interested in handling
> + * conflicts.)
> + *
> + * Since we don't turn on break-rewrites by default, neither
> + * src_entry nor dst_entry can have all three of their stages have
> + * non-null oids, meaning at most four of the six will be non-null.
> + * Also, since this is a rename, both src_entry and dst_entry will
> + * have at least one non-null oid, meaning at least two will be
> + * non-null. Of the six oids, a typical rename will have three be
> + * non-null. Only two implies a rename/delete, and four implies a
> + * rename/add.
> + */
> struct stage_data *src_entry;
> struct stage_data *dst_entry;
> unsigned processed:1;
