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

[Junio C Hamano <gitster@pobox.com>]

Jonathan Nieder <jrnieder@gmail.com> writes:

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