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=-6.3 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,SPF_HELO_NONE, SPF_PASS,URIBL_BLOCKED,USER_AGENT_SANE_2 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 DCF38C4727D for ; Mon, 5 Oct 2020 10:59:34 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id A530520774 for ; Mon, 5 Oct 2020 10:59:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1601895574; bh=zkJ+DHXy7q7U/z6Ji5VotkaUPd9ylktWsmGKNxhDIYc=; h=Date:From:To:Cc:Subject:In-Reply-To:References:List-ID:From; b=qtaptbJ4gafATNrreNUMh2RUn4kMHSGAmn1zaLXqKznTXCdePfxVzLE6kXq7iilal q7zOBkp5OePBVa6KDYYfjDdj4pEPYUxZZnp/U5Zm1rJtg//mYbWHjmoYYUJbZI+ued Brhw7YnuLUIzBYHjS6uanIng/XJLX7r8FXavOITE= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1725940AbgJEK7e (ORCPT ); Mon, 5 Oct 2020 06:59:34 -0400 Received: from mail.kernel.org ([198.145.29.99]:48082 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726003AbgJEK71 (ORCPT ); Mon, 5 Oct 2020 06:59:27 -0400 Received: from coco.lan (ip5f5ad5d6.dynamic.kabel-deutschland.de [95.90.213.214]) (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 2DE5B20774; Mon, 5 Oct 2020 10:59:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1601895566; bh=zkJ+DHXy7q7U/z6Ji5VotkaUPd9ylktWsmGKNxhDIYc=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=hkgD5qroZ/qT4o892izj25+aOklBhSxTv96+V097oVdGNAb1IeZb0ZD/KDmw72FdS W7QMuiNvsRjZYD6ms3j9uM8am5W5K8VeJd8TaRF34qRTv/P2CpmYBrBxCTsiqNtjil Fkky8YQXoAcRBvoWD0aTk+etv0PS+6Ps8nZ03rNk= Date: Mon, 5 Oct 2020 12:59:20 +0200 From: Mauro Carvalho Chehab To: Matthew Wilcox Cc: Linux Doc Mailing List , Jonathan Corbet , linux-kernel@vger.kernel.org, "David S. Miller" , Daniel Vetter , David Airlie , Dmitry Torokhov , Heikki Krogerus , Jakub Kicinski , Jens Axboe , Johannes Berg , Jonathan Cameron , Maarten Lankhorst , Maxime Ripard , Thomas Zimmermann Subject: Re: [PATCH 00/14] get rid of the remaining kernel-doc warnings when building the docs Message-ID: <20201005125920.27a7768d@coco.lan> In-Reply-To: <20201005125111.326ff7e2@coco.lan> References: <20200910181208.GW6583@casper.infradead.org> <20201005125111.326ff7e2@coco.lan> X-Mailer: Claws Mail 3.17.6 (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 Mon, 5 Oct 2020 12:51:11 +0200 Mauro Carvalho Chehab escreveu: > Em Thu, 10 Sep 2020 19:12:08 +0100 > Matthew Wilcox escreveu: > > > On Thu, Sep 10, 2020 at 12:23:53PM +0200, Mauro Carvalho Chehab wrote: > > > As described on its subject, this series finally get rid of all kernel-doc warnings. > > > > > > With this series applied (plus my last series fixing other warnings), building > > > the docs is now clean[1] against next-20200909: > > > > Thanks, this has been a truly heroic effort. > > > > I'd suggest that we change the kernel build to always run the CHKDOC > > instead of at W=1 (or rather, as the patch I just sent out demonstrates, > > not at all (oops)). Otherwise you're just going to have to continue > > doing this. > > It sounds a good idea for me to run kernel-doc with W=1 - or even > better - with allyesconfig/allmodconfig (no matter if W=0/W=1/W=2). > > > At some point, perhaps we can add some other warnings at W=1, like > > an EXPORT_SYMBOL of a function which doesn't have kernel-doc. > > Makes sense, but I suspect that supporting it is not too trivial. > > I mean, a script checking for EXPORT_SYMBOL* should check not > only the C file, but also the included header files, as the > kernel-doc markup can be on one of its includes. > > An enhanced version of something like this: > > > #!/usr/bin/perl > > my $file = shift or die "Need a file name"; > > my @files; > my @exports; > > my $dir = $file; > $dir =~ s,[^\/]+$,,; > > push @files, $file; > open IN, "<$file"; > while () { > push @exports, $1 if (m/^EXPORT_SYMBOL.*\(\s*(\S+)\s*\)/); > push @files, "include/$1" if (m/^\s*#\s*include\s+[\<](\S+)[\>]/); > push @files, "$dir/$1" if (m/^\s*#\s*include\s+[\"](\S+)[\"]/); > } > close IN; > > my $doc; > > foreach my $i (@files) { > $doc .= qx(./scripts/kernel-doc $i 2>/dev/null); > } > > foreach my $e (@exports) { > print "$e doesn't have kernel-doc markups\n" if (!($doc =~ m/\b$e\b/)); > } > > > On simple cases, the above script helps to check what's missing: > > $ ./check_exports drivers/acpi/acpi_lpat.c > > $ ./test drivers/media/v4l2-core/v4l2-common.c > __v4l2_find_nearest_size doesn't have kernel-doc markups > v4l2_apply_frmsize_constraints doesn't have kernel-doc markups > v4l2_fill_pixfmt_mp doesn't have kernel-doc markups > v4l2_fill_pixfmt doesn't have kernel-doc markups > > Yet, it the actual script will also need to handle some special > cases: > > - it should check if the Makefile used by the file has a "-I" directive. > This could be tricky, due to Makefile recursion. Hmm... actually this could be obtained via command line parameters, if the script is called with the same parameter set as the one passed to the C compiler. > - it should also check if there is a kernel-doc entry for such header. > a "git grep" could be used in this case. > - It should also handle the optional arguments of kernel-doc, like > :internal", :external", ":no-identifiers", "identifiers", as it is > possible that there is a kernel-doc entry, but this is excluded > by a kernel-doc modifier. > - It should also check if the exported symbol is a function, > in order to exclude static vars that are exported. > > I suspect that there are several other border cases. > > Thanks, > Mauro Thanks, Mauro