undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

date API: add basic API docs

Browse Source 
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>
This commit is contained in:
Ævar Arnfjörð Bjarmason 2022-02-16 09:14:04 +01:00 committed by Junio C Hamano
parent f184289832
commit 2bacb83466
1 changed files with 22 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
date.h
View File

@ -1,6 +1,12 @@
#ifndef DATE_H
#define DATE_H
/**
* The date mode type. This has DATE_NORMAL at an explicit "= 0" to
* accommodate a memset([...], 0, [...]) initialization when "struct
* date_mode" is used as an embedded struct member, as in the case of
* e.g. "struct pretty_print_context" and "struct rev_info".
*/
enum date_mode_type {
DATE_NORMAL = 0,
DATE_HUMAN,
@ -24,7 +30,7 @@ struct date_mode {
.type = DATE_NORMAL, \
}
/*
/**
* Convenience helper for passing a constant type, like:
*
* show_date(t, tz, DATE_MODE(NORMAL));
@ -32,7 +38,22 @@ struct date_mode {
#define DATE_MODE(t) date_mode_from_type(DATE_##t)
struct date_mode *date_mode_from_type(enum date_mode_type type);
/**
* Format <'time', 'timezone'> into static memory according to 'mode'
* and return it. The mode is an initialized "struct date_mode"
* (usually from the DATE_MODE() macro).
*/
const char *show_date(timestamp_t time, int timezone, const struct date_mode *mode);
/**
* Parse a date format for later use with show_date().
*
* When the "date_mode_type" is DATE_STRFTIME the "strftime_fmt"
* member of "struct date_mode" will be a malloc()'d format string to
* be used with strbuf_addftime().
*/
void parse_date_format(const char *format, struct date_mode *mode);
void show_date_relative(timestamp_t time, struct strbuf *timebuf);
int parse_date(const char *date, struct strbuf *out);
int parse_date_basic(const char *date, timestamp_t *timestamp, int *offset);
@ -41,7 +62,6 @@ void datestamp(struct strbuf *out);
#define approxidate(s) approxidate_careful((s), NULL)
timestamp_t approxidate_careful(const char *, int *);
timestamp_t approxidate_relative(const char *date);
void parse_date_format(const char *format, struct date_mode *mode);
int date_overflows(timestamp_t date);
time_t tm_to_time_t(const struct tm *tm);
#endif