From: Junio C Hamano <gitster@pobox.com>
To: "Đoàn Trần Công Danh" <congdanhqx@gmail.com>
Cc: "skrab-sah via GitGitGadget" <gitgitgadget@gmail.com>,
git@vger.kernel.org, "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
skrab-sah <skrab.sah@gmail.com>
Subject: Re: [PATCH v2] abspath.h file is generated by makeheaders tool
Date: Mon, 17 Oct 2022 11:39:57 -0700 [thread overview]
Message-ID: <xmqqy1tez43m.fsf@gitster.g> (raw)
In-Reply-To: <xmqqsfjn4spf.fsf@gitster.g> (Junio C. Hamano's message of "Sun, 16 Oct 2022 09:51:56 -0700")
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.
next prev parent reply other threads:[~2022-10-17 18:40 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-10-12 8:36 [PATCH] abspath.h file is generated by makeheaders tool skrab-sah via GitGitGadget
2022-10-12 9:04 ` Ævar Arnfjörð Bjarmason
2022-10-13 16:40 ` [PATCH v2] " skrab-sah via GitGitGadget
2022-10-16 9:44 ` Skrab Sah
2022-10-16 13:13 ` Đoàn Trần Công Danh
2022-10-16 16:06 ` Skrab Sah
2022-10-16 16:51 ` Junio C Hamano
2022-10-17 0:34 ` Đoàn Trần Công Danh
2022-10-17 7:55 ` Skrab Sah
2022-10-17 18:39 ` Junio C Hamano [this message]
2022-10-18 0:52 ` Skrab Sah
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqy1tez43m.fsf@gitster.g \
--to=gitster@pobox.com \
--cc=avarab@gmail.com \
--cc=congdanhqx@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=skrab.sah@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).