Received: by 2002:a05:6a10:16a7:0:0:0:0 with SMTP id gp39csp566196pxb; Thu, 5 Nov 2020 07:22:52 -0800 (PST) X-Google-Smtp-Source: ABdhPJxWz+NUDSMJ9wtS32KXzNvanZ5b8nI8Xb2Zq/sSWqs1fr5Aii7dv+5a7a0ryQ2peo+E+OSl X-Received: by 2002:a17:906:4742:: with SMTP id j2mr2692043ejs.247.1604589772698; Thu, 05 Nov 2020 07:22:52 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1604589772; cv=none; d=google.com; s=arc-20160816; b=rpnD1aoTlv4BAqh1UjhvzE05E04dh65PzgmY2S+7A8aL/aKg2btTSDIspqaPSJu5Ae hJ7tkK8cvgTRiFvxdZzAcP8ngoJwxb6ZCQU7MrrMQF2h1/iYjUhGICECeLWJ1HW4RAJA ixr3Y2Q52KYdjBrJgSrJRHACXZwJe/m5AEzckQiGrtrd3PbU6BSSVm38dmKFLIRtSaFE Ts3JtGhHx0Zn03YJH1qLchC7qhecjETkicYf0Qq3/in2VGdbtHrYxa4CdQzZ1ivkfMUC kujmd9RjS79ZtIW9t/9YEt6M+jCWubR/iw8z9npAMQXz2gKl0pXgFPjrOZAglZaEoahB dtNQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :references:in-reply-to:message-id:subject:cc:to:from:date :dkim-signature; bh=J0YCcSKww7CE9d9tS9lnBOtdQth8i3LxU+/O1mBARHI=; b=GVnREDFd/ot9JOWWWjFcl1V4afmhpCTvqPxtUIurjlZfxInFncMFRvgrxUZZkdph0U Q2Mqsl4dcEyZ1z3oB5mXrzkx4QXgBlLdTaaS8E7W3t1shn+V+pIkpz467Bime1IQ8IQW O99vjZUAdaeW8AjNHx8iiqc0iHQ5sH9C/osy4osRY7FfersyvNn5bGrTrwsmpc4W0L0t fJuvVyh2BsNuxJTPnpEPSwazk5lshoOkVwc91OpSl98QpaAMSJNFz4e2ngqtEb6ITfbn LRByosbfSzxGOIEatCQTPsGrybVsHDpznyzMNkWzkH8mnYSjXNBdhWfiQptdUJdkHEou I+7Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@kernel.org header.s=default header.b=FyNfatrW; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [23.128.96.18]) by mx.google.com with ESMTP id e14si1341129ejb.495.2020.11.05.07.22.27; Thu, 05 Nov 2020 07:22:52 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18; Authentication-Results: mx.google.com; dkim=pass header.i=@kernel.org header.s=default header.b=FyNfatrW; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730943AbgKEPVI (ORCPT + 99 others); Thu, 5 Nov 2020 10:21:08 -0500 Received: from mail.kernel.org ([198.145.29.99]:58670 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730660AbgKEPVI (ORCPT ); Thu, 5 Nov 2020 10:21:08 -0500 Received: from coco.lan (ip5f5ad5d8.dynamic.kabel-deutschland.de [95.90.213.216]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 0771F20715; Thu, 5 Nov 2020 15:21:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1604589667; bh=PVzV8RSCyjsTW4bwO+dadmNCZfv25T3pDwXzNyWa+98=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=FyNfatrWi96kOs7jsmCKdPDyXVhzlnyUcdxWjpVXwPoz/7Xc1Is16CsqAbFzFlQtd z/0jqdiIh6zljv63zHsrbdO53wcxDXq0zK02+XwIS5hRi7Kl7AMgO6StSlVvndZlVe h+DmWv62FN83RHu0TBdugjzD8oc08H25KRdsbNBc= Date: Thu, 5 Nov 2020 16:20:59 +0100 From: Mauro Carvalho Chehab To: Matthew Wilcox Cc: Linux Doc Mailing List , Jonathan Corbet , linux-kernel@vger.kernel.org Subject: Re: [PATCH v3 56/56] scrpits: kernel-doc: validate kernel-doc markup with the actual names Message-ID: <20201105162059.366b44bc@coco.lan> In-Reply-To: <20201105150017.GL17076@casper.infradead.org> References: <20201105150017.GL17076@casper.infradead.org> X-Mailer: Claws Mail 3.17.8 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Thu, 5 Nov 2020 15:00:17 +0000 Matthew Wilcox escreveu: > On Fri, Oct 23, 2020 at 06:33:43PM +0200, Mauro Carvalho Chehab wrote: > > Kernel-doc currently expects that the kernel-doc markup to come > > just before the function/enum/struct/union/typedef prototype. > > > > Yet, if it find things like: > > > > /** > > * refcount_add - add a value to a refcount > > * @i: the value to add to the refcount > > * @r: the refcount > > */ > > static inline void __refcount_add(int i, refcount_t *r, int *oldp); > > static inline void refcount_add(int i, refcount_t *r); > > > > Kernel-doc will do the wrong thing: > > I wonder if we could change kernel-doc to be (optionally) less verbose. > If we allowed people to write: > > /** > * Add a value to a refcount. > * @i: The value to add to the refcount > * @r: The refcount > */ > > and had the kernel-doc script pick up the name of the following function > automatically, would that be an improvement we could all agree on? Matthew, As patches are usually generated with -U3, the context lines are not enough to show if a comment preceding a function is a kernel-doc markup or a normal comment. In practice, on some patches at this series, I found real issues because something else was added between the kernel-doc markup and the documented function. So, for me, it sounds a bad idea to remove the function name, as this can be used to detect such issues. Thanks, Mauro