Re: [PATCH] doc: fix the stale link to api-builtin.txt

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 15, 2020, 05:45 UTC
Message-ID: <xmqqimi18fq8.fsf@gitster.c.googlers.com>
In-Reply-To: <20200415031429.GA36683@google.com>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 8 quoted lines

>> + * Changeset History
>> + * -----------------
>> + *
>> + * The following describes how the documentation has finally been placed
>> + * in this file, over the related changesets.
>
> *puzzled* Why is this information being added to the builtin.h file?
> What is the reader trying to do when they read it?

Thanks for an excellent review, but you are being a bit too subtle and/or diplomatic here.

A good rule of thumb to use when judging if a comment is appropriate to have in the tracked data is if it talks about what used to be the case in order to explain why it is in the current shape. Often, such description is useless for people going forward starting from the current codebase, and is better described in the log message, and I think that this is a prime example. As an explanation to justify why it is good to refer to builtin.h from the current documentation that teaches what needs to be done to add a new command, instead of api-builtin.txt, it is valuable to know how the description of the API used to support builtin commands moved over time from place to place (preferrably with references to the commits that did so), and it belongs to the log message of this commit that updates the reference to api-builtin.txt to builtin.h.