1 files changed, 67 insertions, 30 deletions

diff --git a/diffcore.h b/diffcore.h
index a30da161da..7c07347e42 100644
--- a/diffcore.h
+++ b/diffcore.h
@@ -4,6 +4,12 @@
 #ifndef DIFFCORE_H
 #define DIFFCORE_H
 
+#include "cache.h"
+
+struct diff_options;
+struct repository;
+struct userdiff_driver;
+
 /* This header file is internal between diff.c and its diff transformers
  * (e.g. diffcore-rename, diffcore-pickaxe).  Never include this header
  * in anything else.
@@ -22,8 +28,12 @@
 
 #define MINIMUM_BREAK_SIZE     400 /* do not break a file smaller than this */
 
-struct userdiff_driver;
-
+/**
+ * the internal representation for a single file (blob).  It records the blob
+ * object name (if known -- for a work tree file it typically is a NUL SHA-1),
+ * filemode and pathname.  This is what the `diff_addremove()`, `diff_change()`
+ * and `diff_unmerge()` synthesize and feed `diff_queue()` function with.
+ */
 struct diff_filespec {
 	struct object_id oid;
 	char *path;
@@ -50,18 +60,29 @@ struct diff_filespec {
 	struct userdiff_driver *driver;
 };
 
-extern struct diff_filespec *alloc_filespec(const char *);
-extern void free_filespec(struct diff_filespec *);
-extern void fill_filespec(struct diff_filespec *, const struct object_id *,
-			  int, unsigned short);
+struct diff_filespec *alloc_filespec(const char *);
+void free_filespec(struct diff_filespec *);
+void fill_filespec(struct diff_filespec *, const struct object_id *,
+		   int, unsigned short);
 
 #define CHECK_SIZE_ONLY 1
 #define CHECK_BINARY    2
-extern int diff_populate_filespec(struct diff_filespec *, unsigned int);
-extern void diff_free_filespec_data(struct diff_filespec *);
-extern void diff_free_filespec_blob(struct diff_filespec *);
-extern int diff_filespec_is_binary(struct diff_filespec *);
-
+int diff_populate_filespec(struct repository *, struct diff_filespec *, unsigned int);
+void diff_free_filespec_data(struct diff_filespec *);
+void diff_free_filespec_blob(struct diff_filespec *);
+int diff_filespec_is_binary(struct repository *, struct diff_filespec *);
+
+/**
+ * This records a pair of `struct diff_filespec`; the filespec for a file in
+ * the "old" set (i.e. preimage) is called `one`, and the filespec for a file
+ * in the "new" set (i.e. postimage) is called `two`.  A change that represents
+ * file creation has NULL in `one`, and file deletion has NULL in `two`.
+ *
+ * A `filepair` starts pointing at `one` and `two` that are from the same
+ * filename, but `diffcore_std()` can break pairs and match component filespecs
+ * with other filespecs from a different filepair to form new filepair. This is
+ * called 'rename detection'.
+ */
 struct diff_filepair {
 	struct diff_filespec *one;
 	struct diff_filespec *two;
@@ -73,6 +94,7 @@ struct diff_filepair {
 	unsigned done_skip_stat_unmatch : 1;
 	unsigned skip_stat_unmatch_result : 1;
 };
+
 #define DIFF_PAIR_UNMERGED(p) ((p)->is_unmerged)
 
 #define DIFF_PAIR_RENAME(p) ((p)->renamed_pair)
@@ -86,15 +108,29 @@ struct diff_filepair {
 
 #define DIFF_PAIR_MODE_CHANGED(p) ((p)->one->mode != (p)->two->mode)
 
-extern void diff_free_filepair(struct diff_filepair *);
-
-extern int diff_unmodified_pair(struct diff_filepair *);
-
+void diff_free_filepair(struct diff_filepair *);
+
+int diff_unmodified_pair(struct diff_filepair *);
+
+/**
+ * This is a collection of filepairs.  Notable members are:
+ *
+ * - `queue`:
+ * An array of pointers to `struct diff_filepair`. This dynamically grows as
+ * you add filepairs;
+ *
+ * - `alloc`:
+ * The allocated size of the `queue` array;
+ *
+ * - `nr`:
+ * The number of elements in the `queue` array.
+ */
 struct diff_queue_struct {
 	struct diff_filepair **queue;
 	int alloc;
 	int nr;
 };
+
 #define DIFF_QUEUE_CLEAR(q) \
 	do { \
 		(q)->queue = NULL; \
@@ -102,16 +138,16 @@ struct diff_queue_struct {
 	} while (0)
 
 extern struct diff_queue_struct diff_queued_diff;
-extern struct diff_filepair *diff_queue(struct diff_queue_struct *,
-					struct diff_filespec *,
-					struct diff_filespec *);
-extern void diff_q(struct diff_queue_struct *, struct diff_filepair *);
+struct diff_filepair *diff_queue(struct diff_queue_struct *,
+				 struct diff_filespec *,
+				 struct diff_filespec *);
+void diff_q(struct diff_queue_struct *, struct diff_filepair *);
 
-extern void diffcore_break(int);
-extern void diffcore_rename(struct diff_options *);
-extern void diffcore_merge_broken(void);
-extern void diffcore_pickaxe(struct diff_options *);
-extern void diffcore_order(const char *orderfile);
+void diffcore_break(struct repository *, int);
+void diffcore_rename(struct diff_options *);
+void diffcore_merge_broken(void);
+void diffcore_pickaxe(struct diff_options *);
+void diffcore_order(const char *orderfile);
 
 /* low-level interface to diffcore_order */
 struct obj_order {
@@ -138,11 +174,12 @@ void diff_debug_queue(const char *, struct diff_queue_struct *);
 #define diff_debug_queue(a,b) do { /* nothing */ } while (0)
 #endif
 
-extern int diffcore_count_changes(struct diff_filespec *src,
-				  struct diff_filespec *dst,
-				  void **src_count_p,
-				  void **dst_count_p,
-				  unsigned long *src_copied,
-				  unsigned long *literal_added);
+int diffcore_count_changes(struct repository *r,
+			   struct diff_filespec *src,
+			   struct diff_filespec *dst,
+			   void **src_count_p,
+			   void **dst_count_p,
+			   unsigned long *src_copied,
+			   unsigned long *literal_added);
 
 #endif