diff: add a comment about combine_diff_path.parent.path

We only fill in the per-parent "path" field when it differs from what's
in combine_diff_path.path (and even then only when the option is
appropriate). Let's document that.

Suggested-by: Wink Saville <wink@saville.com>
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/diff.h b/diff.h
index f5f6ea00fb3770457984f3badefd497363706bfb..60e7db4ad6cc76efda5005ca04bc13e1ae9d7088 100644 (file)
--- a/diff.h
+++ b/diff.h
@@ -480,6 +480,12 @@ struct combine_diff_path {
                char status;
                unsigned int mode;
                struct object_id oid;
+               /*
+                * This per-parent path is filled only when doing a combined
+                * diff with revs.combined_all_paths set, and only if the path
+                * differs from the post-image (e.g., a rename or copy).
+                * Otherwise it is left NULL.
+                */
                char *path;
        } parent[FLEX_ARRAY];
 };