From 52ed1894b04e7664feaee85c0f14360b415a755c Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Sun, 6 Jan 2013 16:58:06 +0000 Subject: [PATCH] dir.c: improve docs for match_pathspec() and match_pathspec_depth() Fix a grammatical issue in the description of these functions, and make it more obvious how and why seen[] can be reused across multiple invocations. Signed-off-by: Adam Spiers Signed-off-by: Junio C Hamano --- dir.c | 38 ++++++++++++++++++++++++++------------ dir.h | 6 ++++++ 2 files changed, 32 insertions(+), 12 deletions(-) diff --git a/dir.c b/dir.c index 46f362ed69..547b83f210 100644 --- a/dir.c +++ b/dir.c @@ -167,12 +167,19 @@ static int match_one(const char *match, const char *name, int namelen) } /* - * Given a name and a list of pathspecs, see if the name matches - * any of the pathspecs. The caller is also interested in seeing - * all pathspec matches some names it calls this function with - * (otherwise the user could have mistyped the unmatched pathspec), - * and a mark is left in seen[] array for pathspec element that - * actually matched anything. + * Given a name and a list of pathspecs, returns the nature of the + * closest (i.e. most specific) match of the name to any of the + * pathspecs. + * + * The caller typically calls this multiple times with the same + * pathspec and seen[] array but with different name/namelen + * (e.g. entries from the index) and is interested in seeing if and + * how each pathspec matches all the names it calls this function + * with. A mark is left in the seen[] array for each pathspec element + * indicating the closest type of match that element achieved, so if + * seen[n] remains zero after multiple invocations, that means the nth + * pathspec did not match any names, which could indicate that the + * user mistyped the nth pathspec. */ int match_pathspec(const char **pathspec, const char *name, int namelen, int prefix, char *seen) @@ -239,12 +246,19 @@ static int match_pathspec_item(const struct pathspec_item *item, int prefix, } /* - * Given a name and a list of pathspecs, see if the name matches - * any of the pathspecs. The caller is also interested in seeing - * all pathspec matches some names it calls this function with - * (otherwise the user could have mistyped the unmatched pathspec), - * and a mark is left in seen[] array for pathspec element that - * actually matched anything. + * Given a name and a list of pathspecs, returns the nature of the + * closest (i.e. most specific) match of the name to any of the + * pathspecs. + * + * The caller typically calls this multiple times with the same + * pathspec and seen[] array but with different name/namelen + * (e.g. entries from the index) and is interested in seeing if and + * how each pathspec matches all the names it calls this function + * with. A mark is left in the seen[] array for each pathspec element + * indicating the closest type of match that element achieved, so if + * seen[n] remains zero after multiple invocations, that means the nth + * pathspec did not match any names, which could indicate that the + * user mistyped the nth pathspec. */ int match_pathspec_depth(const struct pathspec *ps, const char *name, int namelen, diff --git a/dir.h b/dir.h index dd42a3a061..136e8383fb 100644 --- a/dir.h +++ b/dir.h @@ -116,6 +116,12 @@ struct dir_struct { char basebuf[PATH_MAX]; }; +/* + * The ordering of these constants is significant, with + * higher-numbered match types signifying "closer" (i.e. more + * specific) matches which will override lower-numbered match types + * when populating the seen[] array. + */ #define MATCHED_RECURSIVELY 1 #define MATCHED_FNMATCH 2 #define MATCHED_EXACTLY 3