Junio C Hamano <gitster@xxxxxxxxx> writes:
> 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.
