Subject: Re: [PATCH 4/5] date API: add basic API docs

From: Junio C Hamano <[email-masked]>
Date: Mon, 14 Feb 2022 18:14:25 -0800

Ævar Arnfjörð Bjarmason  <[email-masked]> writes:

> +/**
> + * 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);

It's a bit of wasted bytes to explain "show_date()" as "show".  In
the context of this function, the verb "show" in its name does not
mean emitting to any output stream, but return a short-lived memory
stuffed with a  date string formatted according to the date mode
that the caller needs to either immediately consume or strdup() away
if it wants to use it later, which is a lot more helpful thing to
tell to the readers.

    /**
     * Format <'time', 'timezone'> into static memory according to
     * 'mode' and return it.
     */

or something along that line?