From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 12 Dec 2014 22:16:32 GMT
Subject: Re: [PATCH 1/4] strbuf: migrate api-strbuf.txt documentation to strbuf.h
Message-ID: <xmqqoar8ecov.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20141212212800.GA27451@peff.net>

Jeff King <peff@peff.net> writes:

> +/**
> + * * Related to the contents of the buffer
> + */
> +
> +/**
> + * Strip whitespace from the beginning and end of a string.
> + * Equivalent to performing `strbuf_rtrim()` followed by `strbuf_ltrim()`.
> + */
>  extern void strbuf_trim(struct strbuf *);
> +
> +/**
> + * Strip whitespace from the end of a string.
> + */
>  extern void strbuf_rtrim(struct strbuf *);
> +
> +/**
> + * Strip whitespace from the beginning of a string.
> + */
>  extern void strbuf_ltrim(struct strbuf *);

This part reminds me why I often find the current "out of header"
documentation when writing code _without_ the need for _learning_
the API.  The corresponding part in the original is merely these:

    /*----- content related -----*/
    extern void strbuf_trim(struct strbuf *);
    extern void strbuf_rtrim(struct strbuf *);
    extern void strbuf_ltrim(struct strbuf *);
    extern int strbuf_reencode(struct strbuf *sb, const char *from, const char *to);
    ...

It is a lot quicker, scanning this with eyeball, to notice that
there are three related "trim" functions and how they are spelled.
If I wanted to "trim from both ends", knew there were some ways to
"trim" but didn't remember if we had r/ltrim without trim, and/or
was not sure if the "both" version was was _trim or _btrim, scanning
a bland list tends to be much more pleasant.

When you are _learning_ the API, the format that spreads each
individual function into its own section with explanation would be
easier to read through.

Not a strong objection to the overall direction, but I think that we
need to be aware that we are making things harder for some use
cases.