Re: [PATCH 1/4] strbuf: migrate api-strbuf.txt documentation to strbuf.h

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 12, 2014, 22:16 UTC
Message-ID: <xmqqoar8ecov.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20141212212800.GA27451@peff.net>

Jeff King <peff@peff.net> writes:

Show 19 quoted lines

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