From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: * X-Spam-ASN: AS3215 2.6.0.0/16 X-Spam-Status: No, score=1.4 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,LIST_MIRROR_RECEIVED,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS,T_SCC_BODY_TEXT_LINE shortcircuit=no autolearn=no autolearn_force=no version=3.4.2 Received: from out1.vger.email (out1.vger.email [IPv6:2620:137:e000::1:20]) by dcvr.yhbt.net (Postfix) with ESMTP id 588AA1F953 for ; Fri, 4 Feb 2022 23:53:24 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1378384AbiBDXxT (ORCPT ); Fri, 4 Feb 2022 18:53:19 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:50888 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1378268AbiBDXxP (ORCPT ); Fri, 4 Feb 2022 18:53:15 -0500 Received: from mail-wr1-x42b.google.com (mail-wr1-x42b.google.com [IPv6:2a00:1450:4864:20::42b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 61FE3C104372 for ; Fri, 4 Feb 2022 15:53:14 -0800 (PST) Received: by mail-wr1-x42b.google.com with SMTP id m14so13987805wrg.12 for ; Fri, 04 Feb 2022 15:53:14 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=CxIExHfpQA96SI5C5xne6UDjJJzbSBpJheF8LtY9FDs=; b=GjKx4nLSVOctG6ugczEMvwoHf8cTlNNxIXc3p6Lavfv6mNehrxyEM00mBoDNeHoAGK IaBQC3Rh+Rz9UXj2fKSoReMoPKZZu2CtoQxq9+jIEAH/KP7qdQgkTiOGhP64mziwwY6p HfMLySIrdbI5jpaQ+aTM86wt3/BrHVuvcWpKXi4g6dSD/Kd8ZpuXwZcIcGgxMTzvku3H Ybrg8BFZ0Z19Syc51zs9lMbyQgrDnOxFFOeJUEcVcuv7FPiuZrUoGnTBGbtNnuerWHxe 2FYW7cOefPJfX7Y3zi4Cm3bFGZocd2G+RrMgNN1gXE61huIlMuGOMgrHu1GAp0QWyGk8 5wXQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=CxIExHfpQA96SI5C5xne6UDjJJzbSBpJheF8LtY9FDs=; b=sRLktTcfYCL3nyVm9Jwyh9WtgvM5tSiNCK0U+Z8jRXVIKVHhnT78lBuvSkgglxqNwV 7n5kJiVO7OP8cN/zEJtOsd2X5+SIpgntx9R85dtHLP/fdQs8wrUxjaJEeRlChgy/tyb9 SMiwBwgrBZcyC93XDZnRBDg4qhHiNR5VP5UavrWmHm/SF2TAHotshQ+SuJEqHEx/XcY6 9oeqy475CZlACgnxkElTxHRGOqspJGn2Nsxg0oKa6mI988FAlKNSMkAFli8EELGTm57x P3mjWJAeKZTh9zegcNcTux8EL2piFbhbcFX8aCZvlXxPcDHnZ37LeY2I2RASdq4YIe9f cuzg== X-Gm-Message-State: AOAM531TUYS5/mcmwWh4KG4/h82XyWJ3T/HJkVWh/bUgDvu964D7bLAd giaEpl+/mblyEbuWaDuUMnPGCKvZZxBIdw== X-Google-Smtp-Source: ABdhPJxteiC39g2vv1FxezgjoCO3x4+iEKe0jcT1W1z6WJzZFc7sUHpr38rQEpvg7Kf5I9lpkTvooA== X-Received: by 2002:a5d:6686:: with SMTP id l6mr994024wru.314.1644018792733; Fri, 04 Feb 2022 15:53:12 -0800 (PST) Received: from vm.nix.is (vm.nix.is. [2a01:4f8:120:2468::2]) by smtp.gmail.com with ESMTPSA id a18sm3304507wrw.5.2022.02.04.15.53.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 04 Feb 2022 15:53:12 -0800 (PST) From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= To: git@vger.kernel.org Cc: Junio C Hamano , Jeff King , =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Subject: [PATCH v2 4/5] date API: add basic API docs Date: Sat, 5 Feb 2022 00:53:05 +0100 Message-Id: X-Mailer: git-send-email 2.35.1.940.ge7a5b4b05f2 In-Reply-To: References: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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 --- date.h | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/date.h b/date.h index c3a00d08ed6..4ed83506de9 100644 --- a/date.h +++ b/date.h @@ -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,21 @@ 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); +/** + * Show the date given 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 +61,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 -- 2.35.1.940.ge7a5b4b05f2