From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0BFC6C4332F for ; Mon, 17 Oct 2022 18:40:06 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229996AbiJQSkE (ORCPT ); Mon, 17 Oct 2022 14:40:04 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:38370 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229770AbiJQSkD (ORCPT ); Mon, 17 Oct 2022 14:40:03 -0400 Received: from pb-smtp2.pobox.com (pb-smtp2.pobox.com [64.147.108.71]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5A3E3642FA for ; Mon, 17 Oct 2022 11:40:01 -0700 (PDT) Received: from pb-smtp2.pobox.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id 3F1FE147410; Mon, 17 Oct 2022 14:40:00 -0400 (EDT) (envelope-from junio@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=sasl; bh=Y8n2/cdTfNTxGeo9wWepJBPNOGZJ4DuKxv9KSB boPXQ=; b=NiO/R7CqR4cxfhyHuVFy+UBpno15VcaaGmL8NN5PCW+B2bh/lmq1S5 CEp5KvsbgHO60ABkYxiuIgwbEjDbBS5cmpi8eApm1bgb87tb2j/6VVLI/PFyIXXt At9uS8XuKGpcEKNnULYJGHQydidfpyl+KmFdCQSc5F7dul08u/Ybk= Received: from pb-smtp2.nyi.icgroup.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id 2E80C14740D; Mon, 17 Oct 2022 14:39:59 -0400 (EDT) (envelope-from junio@pobox.com) Received: from pobox.com (unknown [34.83.5.33]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp2.pobox.com (Postfix) with ESMTPSA id 84316147407; Mon, 17 Oct 2022 14:39:58 -0400 (EDT) (envelope-from junio@pobox.com) From: Junio C Hamano To: =?utf-8?B?xJBvw6BuIFRy4bqnbiBDw7RuZw==?= Danh Cc: skrab-sah via GitGitGadget , git@vger.kernel.org, =?utf-8?B?w4Z2YXIgQXJuZmrDtnLDsA==?= Bjarmason , skrab-sah Subject: Re: [PATCH v2] abspath.h file is generated by makeheaders tool References: Date: Mon, 17 Oct 2022 11:39:57 -0700 In-Reply-To: (Junio C. Hamano's message of "Sun, 16 Oct 2022 09:51:56 -0700") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Pobox-Relay-ID: 1A17BBC6-4E4B-11ED-A1BF-307A8E0A682E-77302942!pb-smtp2.pobox.com Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Junio C Hamano 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 .c described in .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.