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 X-Spam-Level: X-Spam-Status: No, score=-5.8 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4CED0C433E0 for ; Thu, 18 Mar 2021 16:38:13 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 0378164F11 for ; Thu, 18 Mar 2021 16:38:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231963AbhCRQhk (ORCPT ); Thu, 18 Mar 2021 12:37:40 -0400 Received: from ms.lwn.net ([45.79.88.28]:52030 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232134AbhCRQhY (ORCPT ); Thu, 18 Mar 2021 12:37:24 -0400 Received: from localhost (unknown [IPv6:2601:281:8300:104d::5f6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id E2D732E5; Thu, 18 Mar 2021 16:37:23 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E2D732E5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1616085444; bh=pWbzF1wgIUiO8lLs6lJoTFe088GpnU5XVDRIVFq/5Ok=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=e48pDaT9fmQ8ixzvsSt301dPeftXj1BshL6H+kPC2MY4a6u0bbOAMG4LNpdSgJstY sFXGk34Yr/N8e6t3VUsM2rCY5hxqBaF3gQvBXQuhcv85gVG2FrmwttrZH6LnONjHq2 9xezEugy1o4JuPHcj4sCcFyhFrcbwWunDddU/QtI7jsyCx4+xgU5Y1oydtDO37lxD1 E9oMvfouS4woufuQya2qosW04wCJITiQprm/D9jlbmtBT2GwPUswd+E8N8ZJY1CJ2g z6qLze5ecujERovNo3M3BgdgQSYVeJLsEPUXN/0vN/vKCzKgg0zm2I5OLyhoKMfIDe u3WwinKUwyxiA== From: Jonathan Corbet To: Lukas Bulwahn Cc: Aditya , Markus Heiser , "open list:DOCUMENTATION" , Linux Kernel Mailing List , linux-kernel-mentees@lists.linuxfoundation.org Subject: Re: [RFC] scripts: kernel-doc: avoid warnings due to initial commented lines in file In-Reply-To: References: <20210309125324.4456-1-yashsri421@gmail.com> <8959bf29-9ee1-6a1d-da18-f440232864f3@darmarit.de> <871rcg2p8g.fsf@meer.lwn.net> Date: Thu, 18 Mar 2021 10:37:23 -0600 Message-ID: <878s6kto3g.fsf@meer.lwn.net> MIME-Version: 1.0 Content-Type: text/plain Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Lukas Bulwahn writes: > I wonder if we could extend kernel-doc (not your preferred option as > it seems) for a new dedicated warning message or maintain a separate > kernel-doc sanity checking script to emit a dedicated warning based on > some heuristics that suggests when a "header comment" is probably > unintentionally declared as a "kernel-doc comment" when it really > should not be. > > Jonathan, would you then prefer to have a separate kernel-doc sanity > checking script that then allows us to maintain checking for patterns > we already cleaned up? Having a warning in kernel-doc for "This comment starts with /** but isn't a kerneldoc comment" could be useful, I guess. That is the real problem, not the fact that it appears at the top of the file. I'm all for tools that help us to clean things up, but let's not add line-counting hacks to try to paper it over. Thanks, jon 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 X-Spam-Level: X-Spam-Status: No, score=-3.5 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,URIBL_BLOCKED autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 046F6C433DB for ; Thu, 18 Mar 2021 16:37:29 +0000 (UTC) Received: from smtp1.osuosl.org (smtp1.osuosl.org [140.211.166.138]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 8F31364E20 for ; Thu, 18 Mar 2021 16:37:28 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 8F31364E20 Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=lwn.net Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=linux-kernel-mentees-bounces@lists.linuxfoundation.org Received: from localhost (localhost [127.0.0.1]) by smtp1.osuosl.org (Postfix) with ESMTP id 5AC4F8354B; Thu, 18 Mar 2021 16:37:28 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from smtp1.osuosl.org ([127.0.0.1]) by localhost (smtp1.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id Lcdmw-alhKh8; Thu, 18 Mar 2021 16:37:27 +0000 (UTC) Received: from lists.linuxfoundation.org (lf-lists.osuosl.org [IPv6:2605:bc80:3010:104::8cd3:938]) by smtp1.osuosl.org (Postfix) with ESMTP id 8D1268341E; Thu, 18 Mar 2021 16:37:27 +0000 (UTC) Received: from lf-lists.osuosl.org (localhost [127.0.0.1]) by lists.linuxfoundation.org (Postfix) with ESMTP id 66889C000A; Thu, 18 Mar 2021 16:37:27 +0000 (UTC) Received: from smtp2.osuosl.org (smtp2.osuosl.org [140.211.166.133]) by lists.linuxfoundation.org (Postfix) with ESMTP id 13F89C0001 for ; Thu, 18 Mar 2021 16:37:26 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by smtp2.osuosl.org (Postfix) with ESMTP id DBD02400B5 for ; Thu, 18 Mar 2021 16:37:25 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Authentication-Results: smtp2.osuosl.org (amavisd-new); dkim=pass (2048-bit key) header.d=lwn.net Received: from smtp2.osuosl.org ([127.0.0.1]) by localhost (smtp2.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id Abaz3xnldlLI for ; Thu, 18 Mar 2021 16:37:24 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.8.0 Received: from ms.lwn.net (ms.lwn.net [IPv6:2600:3c01:e000:3a1::42]) by smtp2.osuosl.org (Postfix) with ESMTPS id C8E04400AB for ; Thu, 18 Mar 2021 16:37:24 +0000 (UTC) Received: from localhost (unknown [IPv6:2601:281:8300:104d::5f6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id E2D732E5; Thu, 18 Mar 2021 16:37:23 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net E2D732E5 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1616085444; bh=pWbzF1wgIUiO8lLs6lJoTFe088GpnU5XVDRIVFq/5Ok=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=e48pDaT9fmQ8ixzvsSt301dPeftXj1BshL6H+kPC2MY4a6u0bbOAMG4LNpdSgJstY sFXGk34Yr/N8e6t3VUsM2rCY5hxqBaF3gQvBXQuhcv85gVG2FrmwttrZH6LnONjHq2 9xezEugy1o4JuPHcj4sCcFyhFrcbwWunDddU/QtI7jsyCx4+xgU5Y1oydtDO37lxD1 E9oMvfouS4woufuQya2qosW04wCJITiQprm/D9jlbmtBT2GwPUswd+E8N8ZJY1CJ2g z6qLze5ecujERovNo3M3BgdgQSYVeJLsEPUXN/0vN/vKCzKgg0zm2I5OLyhoKMfIDe u3WwinKUwyxiA== From: Jonathan Corbet To: Lukas Bulwahn Subject: Re: [RFC] scripts: kernel-doc: avoid warnings due to initial commented lines in file In-Reply-To: References: <20210309125324.4456-1-yashsri421@gmail.com> <8959bf29-9ee1-6a1d-da18-f440232864f3@darmarit.de> <871rcg2p8g.fsf@meer.lwn.net> Date: Thu, 18 Mar 2021 10:37:23 -0600 Message-ID: <878s6kto3g.fsf@meer.lwn.net> MIME-Version: 1.0 Cc: Markus Heiser , "open list:DOCUMENTATION" , linux-kernel-mentees@lists.linuxfoundation.org, Linux Kernel Mailing List , Aditya X-BeenThere: linux-kernel-mentees@lists.linuxfoundation.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: linux-kernel-mentees-bounces@lists.linuxfoundation.org Sender: "Linux-kernel-mentees" Lukas Bulwahn writes: > I wonder if we could extend kernel-doc (not your preferred option as > it seems) for a new dedicated warning message or maintain a separate > kernel-doc sanity checking script to emit a dedicated warning based on > some heuristics that suggests when a "header comment" is probably > unintentionally declared as a "kernel-doc comment" when it really > should not be. > > Jonathan, would you then prefer to have a separate kernel-doc sanity > checking script that then allows us to maintain checking for patterns > we already cleaned up? Having a warning in kernel-doc for "This comment starts with /** but isn't a kerneldoc comment" could be useful, I guess. That is the real problem, not the fact that it appears at the top of the file. I'm all for tools that help us to clean things up, but let's not add line-counting hacks to try to paper it over. Thanks, jon _______________________________________________ Linux-kernel-mentees mailing list Linux-kernel-mentees@lists.linuxfoundation.org https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees