Show 57 quoted lines
>
> Junio C Hamano <gitster@pobox.com> 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.