Re: [PATCH] document index_name_pos

From: Stefan Beller <sbeller@google.com>
Date: Jan 17, 2017, 21:47 UTC
Message-ID: <CAGZ79kbZamLJqPW-sajL4LUxbJHo_v9j0S=_nLwA30JCYmqQLQ@mail.gmail.com>
In-Reply-To: <xmqqo9z5cqh8.fsf@gitster.mtv.corp.google.com>

On Tue, Jan 17, 2017 at 1:43 PM, Junio C Hamano <gitster@pobox.com> wrote:

Show 21 quoted lines

> Stefan Beller <sbeller@google.com> writes:
>
>> Signed-off-by: Stefan Beller <sbeller@google.com>
>> ---
>>
>>> These placeholders are meant to encourage those people who dove into
>>> the code to update it, so from that point of view, I think removing
>>> it is backwards.
>>
>> Yes, I am currently understanding and writing up documentation for
>> index_name_pos. If I recall the latest discussion where we want to have
>> documentation, I think a quorum favored documentation in the header itself,
>> c.f. strbuf.h, string-list.h for the most desired state. (Although we do have
>> Documentation/technical/api-string-list.txt as well ...)
>>
>> So maybe starting like this?
>
> That is very good.  Let's drop that file from Documentation/technical
> and do it like this (meaning, take both patches from you).
>
> Thanks.

This patch is incorrect, as we need to do s/b -> -1/b -> -2/. (Wrong documentation is the worst)

Also we'd probably want to see more of the functions documented. I'll see if I can extend this into a series documenting more functions.

Thanks, Stefan