OK. On Tue, 18 Oct 2022 at 00:10, Junio C Hamano <gitster@xxxxxxxxx> wrote: > > 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.
