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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 15, 2022, 02:14 UTC
Message-ID: <xmqqtud0zxj2.fsf@gitster.g>
In-Reply-To: <patch-4.5-aab2ae9cc72-20220202T195651Z-avarab@gmail.com>

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

Show 5 quoted lines

> +/**
> + * 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?