date API: add basic API docs
Add basic API doc comments to date.h, and while doing so move the the parse_date_format() function adjacent to show_date(). This way all the "struct date_mode" functions are grouped together. Documenting the rest is one of our #leftoverbits. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Feb 16, 2022 at 09:14 UTC
2bacb8346660b54dc4440da44103a7cd3d469009
1 file changed
+22
-2
date.h
+22
-2
@@ -1,6 +1,12 @@
1
#ifndef DATE_H
2
#define DATE_H
3
4
+/**
5
+ * The date mode type. This has DATE_NORMAL at an explicit "= 0" to
6
+ * accommodate a memset([...], 0, [...]) initialization when "struct
7
+ * date_mode" is used as an embedded struct member, as in the case of
8
+ * e.g. "struct pretty_print_context" and "struct rev_info".
9
+ */
10
enum date_mode_type {
11
DATE_NORMAL = 0,
12
DATE_HUMAN,
@@ -24,7 +30,7 @@ struct date_mode {
30
.type = DATE_NORMAL, \
31
}
32
27
-/*
33
+/**
34
* Convenience helper for passing a constant type, like:
35
*
36
* show_date(t, tz, DATE_MODE(NORMAL));
@@ -32,7 +38,22 @@ struct date_mode {
38
#define DATE_MODE(t) date_mode_from_type(DATE_##t)
39
struct date_mode *date_mode_from_type(enum date_mode_type type);
40
41
+/**
42
+ * Format <'time', 'timezone'> into static memory according to 'mode'
43
+ * and return it. The mode is an initialized "struct date_mode"
44
+ * (usually from the DATE_MODE() macro).
45
+ */
46
const char *show_date(timestamp_t time, int timezone, const struct date_mode *mode);
47
+
48
+/**
49
+ * Parse a date format for later use with show_date().
50
+ *
51
+ * When the "date_mode_type" is DATE_STRFTIME the "strftime_fmt"
52
+ * member of "struct date_mode" will be a malloc()'d format string to
53
+ * be used with strbuf_addftime().
54
+ */
55
+void parse_date_format(const char *format, struct date_mode *mode);
56
+
57
void show_date_relative(timestamp_t time, struct strbuf *timebuf);
58
int parse_date(const char *date, struct strbuf *out);
59
int parse_date_basic(const char *date, timestamp_t *timestamp, int *offset);
@@ -41,7 +62,6 @@ void datestamp(struct strbuf *out);
62
#define approxidate(s) approxidate_careful((s), NULL)
63
timestamp_t approxidate_careful(const char *, int *);
64
timestamp_t approxidate_relative(const char *date);
44
-void parse_date_format(const char *format, struct date_mode *mode);
65
int date_overflows(timestamp_t date);
66
time_t tm_to_time_t(const struct tm *tm);
67
#endif