From a64e6a44c63a965c5bc26242ddd3ed049b42e117 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Mon, 22 Feb 2016 13:28:54 -0500 Subject: diff: clarify textconv interface The memory allocation scheme for the textconv interface is a bit tricky, and not well documented. It was originally designed as an internal part of diff.c (matching fill_mmfile), but gradually was made public. Refactoring it is difficult, but we can at least improve the situation by documenting the intended flow and enforcing it with an in-code assertion. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- diff.h | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'diff.h') diff --git a/diff.h b/diff.h index 1ac0582228..65a5e78f64 100644 --- a/diff.h +++ b/diff.h @@ -342,10 +342,26 @@ extern void diff_no_index(struct rev_info *, int, const char **, const char *); extern int index_differs_from(const char *def, int diff_flags); +/* + * Fill the contents of the filespec "df", respecting any textconv defined by + * its userdiff driver. The "driver" parameter must come from a + * previous call to get_textconv(), and therefore should either be NULL or have + * textconv enabled. + * + * Note that the memory ownership of the resulting buffer depends on whether + * the driver field is NULL. If it is, then the memory belongs to the filespec + * struct. If it is non-NULL, then "outbuf" points to a newly allocated buffer + * that should be freed by the caller. + */ extern size_t fill_textconv(struct userdiff_driver *driver, struct diff_filespec *df, char **outbuf); +/* + * Look up the userdiff driver for the given filespec, and return it if + * and only if it has textconv enabled (otherwise return NULL). The result + * can be passed to fill_textconv(). + */ extern struct userdiff_driver *get_textconv(struct diff_filespec *one); extern int parse_rename_score(const char **cp_p); -- cgit v1.2.1