Re: [PATCH v2] abspath.h file is generated by makeheaders tool

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 17, 2022, 18:39 UTC
Message-ID: <xmqqy1tez43m.fsf@gitster.g>
In-Reply-To: <xmqqsfjn4spf.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

Show 6 quoted lines

> Whether the headers mechanically generated gets committed or not,
> this line of change is unwelcome.  Developers should be able to look
> at the header files (and interface document, if we ever generate one
> out of structured comments in the header files) when using common
> functions that they are not (yet) familiar with, and we want to see
> our header files manually curated.

I would presume that a possible topic that involve an abspath.h header file that did not exist may fly much better if the story were this way instead:

    A developer was working on on something and needed to use some
    function or two in abspath.c that did not have a good
    explanation in how to use them, what pre- and post- conditions
    they required, etc.  Naturally, because the developer previously
    learned how to use functions in dir.c by seeing dir.h and found
    it a very convenient way to look for things in <frotz>.c
    described in <frotz>.h, the developer expected to find in
    abspath.h everything necessary to use the functions.  But the
    file did not exist.  Instead, interfaces were declared in a more
    central header file.  Hence the developer proposed to create
    abspath.h and declare and document extern functions defined in
    abspath.c in the new header file.  Some in-code comment in front
    of the function definition in abspath.c are also moved to
    abspath.h as part of such a change.  And the new file is added
    and tracked, so we can "git blame" the header file from that
    point on.

The end result and how that end result brings goodness to the world matters. With such a change, we will have a curated and tracked header file that helps our developers to use the API correctly, and it may make it easier than the status quo. One thing to note in the above hypothetical story is that it does not matter what tool the developer used (or did not use) to prepare the initial draft of the abspath.h header file.

And "initial draft" is an important part of the above sentence. I do not think automated tool can produce 100% acceptable final result. The natural order of presenting multiple functions defined and associated structure types used in the source may be different from how they appear in the source file, and there may need to be additional API comment for group of functions added, etc. But if an automation can help preparing the initial draft, I wouldn't forbid the use of such a tool. It's just that the initial draft needs to be polished before getting presented to us, and at that point, nobody even needs to know how the initial draft was produced.

The two attempts looked more like "I want to find a way to use this tool, please help me", to which a responsible maintainer has to say "no, please don't". The thing is, we do not want to have to use it ourselves ongoing basis while maintaining abspath.h header file or abspath.c source file or Git source code in general.

Thanks.