From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS3215 2.6.0.0/16 X-Spam-Status: No, score=-3.7 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from out1.vger.email (out1.vger.email [IPv6:2620:137:e000::1:20]) by dcvr.yhbt.net (Postfix) with ESMTP id 808EA1F403 for ; Tue, 18 Oct 2022 00:54:41 +0000 (UTC) Authentication-Results: dcvr.yhbt.net; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="ZGUAWYYH"; dkim-atps=neutral Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229874AbiJRAw6 (ORCPT ); Mon, 17 Oct 2022 20:52:58 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:46588 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230503AbiJRAwl (ORCPT ); Mon, 17 Oct 2022 20:52:41 -0400 Received: from mail-ej1-x632.google.com (mail-ej1-x632.google.com [IPv6:2a00:1450:4864:20::632]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 30E078260C for ; Mon, 17 Oct 2022 17:52:40 -0700 (PDT) Received: by mail-ej1-x632.google.com with SMTP id d26so28701647ejc.8 for ; Mon, 17 Oct 2022 17:52:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=hNGnthd6t+QWdfZbBoaRfYuOKqBymT6lsefnykAHLUc=; b=ZGUAWYYHj1/PfEHyL+bOY7eAUPDa0KGOjgOhQsZ6zP0Eyer+OsCvBQryajwL33uUSe b+nf213lY1W/iZsc6nSSnGxOJjbUdTUONEuxeuXt2TzjojSf+efwx87ZpZicUorG7OVw cemMKkWE8hNO6IXKPLM4stbMtmP0FFehrzUxxO7f8JCgUyQ3J8YbdNTxjazbvKtKT0Pi s54etQQ9khAEmsgnEhfpWlreyazhqeHOFmB8PQFAn5PXQmYfbvJ6Rtg6OP2StihrlWKv mH3H2Hao5XphBpcuVKY2xzO8q+L+jDyfWfc2Boz7PshifDEXStFbJoOV9fDlXZS2EiuB HuYA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=hNGnthd6t+QWdfZbBoaRfYuOKqBymT6lsefnykAHLUc=; b=AO8vkLI6vmq45flFRo82VFtmDJ2+1sekg5lF+M7kTmHd+iLmeP9EtW9BuGbl7G7aoV sVZd4BwBKq9k2H9qdjBxNVOtbwYcMFWgUoEJ8OaxdzCA2dSPOLUpOdvDMrxwTOKhifhQ xxBb75c9wJZIrSHA3LYv2vKEsOchgoQBg9AyllYz4XzkeK/lwsMq9UKVG/eaJyktsU7I BFSJM5oRY5G4EX0qORYoPe89uOqrHasJYw2wYnPh7/L8eKlJAa5hdBQXLKZUlf4Tuctb w9WdlumsjUkrTghP5NF4uXK+ZqXAJlNno+lwSlJMybzHaXpSfb9/5PvloPk9IWCI3Ges dqkg== X-Gm-Message-State: ACrzQf1H97t/kW+gwd/6ULfzHyP40XNxJ4WnoA7ThXFjHTDsS8R1W1FC NkK17YVDG5/R6jX39e3Zlf/JacNBaKpb/TAz15waqGhV X-Google-Smtp-Source: AMsMyM5ikft3bjwbB5ji4yQDCAqnXA2RzaFUwnR6NL2DOZv4TErZ2HweGG8hjnoffNa1XXpKMz91OucU5QgW4cO1F8M= X-Received: by 2002:a17:906:9bf4:b0:78d:8893:7f77 with SMTP id de52-20020a1709069bf400b0078d88937f77mr301533ejc.349.1666054358621; Mon, 17 Oct 2022 17:52:38 -0700 (PDT) MIME-Version: 1.0 References: In-Reply-To: From: Skrab Sah Date: Tue, 18 Oct 2022 06:22:26 +0530 Message-ID: Subject: Re: [PATCH v2] abspath.h file is generated by makeheaders tool To: Junio C Hamano Cc: =?UTF-8?B?xJBvw6BuIFRy4bqnbiBDw7RuZyBEYW5o?= , skrab-sah via GitGitGadget , git@vger.kernel.org, =?UTF-8?B?w4Z2YXIgQXJuZmrDtnLDsCBCamFybWFzb24=?= Content-Type: text/plain; charset="UTF-8" Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org OK. On Tue, 18 Oct 2022 at 00:10, Junio C Hamano wrote: > > 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.