@matheusbsbs / matheus-bagliano / commits / 69ddd231fe

cache.h: clarify documentation for git_path, et al

The comment above these functions actually describes sha1_file_name, and comes from the very first revision of git. Commit 723c31f (Add "git_path()" and "head_ref()" helper functions., 2005-07-05) added git_path, pushing the comment away from the function it describes; later commits added more functions in this block. Let's fix the comment to describe these related functions in more detail. Let's also make sure to point out their safer alternatives (and move those alternatives below, which makes more sense when reading the file). Note that we do not need to move the existing comment to sha1_file_name. Commit d40d535 (sha1_file.c: document a bunch of functions defined in the file, 2014-02-21) already added a much more descriptive comment to it. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Jeff King committed Aug 10, 2015 at 05:32 UTC 69ddd231fe8d4de64990d42b96d34940a7e43aef
1 file changed +12 -5
cache.h
+12 -5
@@ -708,6 +708,18 @@ extern int check_repository_format(void);
708 #define DATA_CHANGED 0x0020
709 #define TYPE_CHANGED 0x0040
710
711 +/*
712 + * Return a statically allocated filename, either generically (mkpath), in
713 + * the repository directory (git_path), or in a submodule's repository
714 + * directory (git_path_submodule). In all cases, note that the result
715 + * may be overwritten by another call to _any_ of the functions. Consider
716 + * using the safer "dup" or "strbuf" formats below.
717 + */
718 +extern const char *mkpath(const char *fmt, ...) __attribute__((format (printf, 1, 2)));
719 +extern const char *git_path(const char *fmt, ...) __attribute__((format (printf, 1, 2)));
720 +extern const char *git_path_submodule(const char *path, const char *fmt, ...)
721 + __attribute__((format (printf, 2, 3)));
722 +
723 extern char *mksnpath(char *buf, size_t n, const char *fmt, ...)
724 __attribute__((format (printf, 3, 4)));
725 extern void strbuf_git_path(struct strbuf *sb, const char *fmt, ...)
@@ -717,11 +729,6 @@ extern char *git_pathdup(const char *fmt, ...)
729 extern char *mkpathdup(const char *fmt, ...)
730 __attribute__((format (printf, 1, 2)));
731
720 -/* Return a statically allocated filename matching the sha1 signature */
721 -extern const char *mkpath(const char *fmt, ...) __attribute__((format (printf, 1, 2)));
722 -extern const char *git_path(const char *fmt, ...) __attribute__((format (printf, 1, 2)));
723 -extern const char *git_path_submodule(const char *path, const char *fmt, ...)
724 - __attribute__((format (printf, 2, 3)));
732 extern void report_linked_checkout_garbage(void);
733
734 /*