From: Skrab Sah <skrab.sah@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Đoàn Trần Công Danh" <congdanhqx@gmail.com>,
"skrab-sah via GitGitGadget" <gitgitgadget@gmail.com>,
git@vger.kernel.org, "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Subject: Re: [PATCH v2] abspath.h file is generated by makeheaders tool
Date: Tue, 18 Oct 2022 06:22:26 +0530 [thread overview]
Message-ID: <CA+J78MUqd3kMuLPXHk3psqYgGUbJhoQCT-1be80sfmfcLTjL9A@mail.gmail.com> (raw)
In-Reply-To: <xmqqy1tez43m.fsf@gitster.g>
OK.
On Tue, 18 Oct 2022 at 00:10, Junio C Hamano <gitster@pobox.com> wrote:
>
> 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.
prev parent reply other threads:[~2022-10-18 0:53 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
2022-10-18 0:52 ` Skrab Sah [this message]
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=CA+J78MUqd3kMuLPXHk3psqYgGUbJhoQCT-1be80sfmfcLTjL9A@mail.gmail.com \
--to=skrab.sah@gmail.com \
--cc=avarab@gmail.com \
--cc=congdanhqx@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=gitster@pobox.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).