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 kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id D0BA4C48BF8 for ; Mon, 19 Feb 2024 22:45:47 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 36AD46B0074; Mon, 19 Feb 2024 17:45:47 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 31ACE6B0078; Mon, 19 Feb 2024 17:45:47 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 1BC306B007B; Mon, 19 Feb 2024 17:45:47 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0013.hostedemail.com [216.40.44.13]) by kanga.kvack.org (Postfix) with ESMTP id 0A5906B0074 for ; Mon, 19 Feb 2024 17:45:47 -0500 (EST) Received: from smtpin11.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay03.hostedemail.com (Postfix) with ESMTP id D5D6FA046C for ; Mon, 19 Feb 2024 22:45:46 +0000 (UTC) X-FDA: 81810037092.11.A9B9430 Received: from smtp-out1.suse.de (smtp-out1.suse.de [195.135.223.130]) by imf19.hostedemail.com (Postfix) with ESMTP id 7FE131A0017 for ; Mon, 19 Feb 2024 22:45:44 +0000 (UTC) Authentication-Results: imf19.hostedemail.com; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=ffBLsxdk; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=qSDppZHj; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=ffBLsxdk; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=qSDppZHj; dmarc=pass (policy=none) header.from=suse.de; spf=pass (imf19.hostedemail.com: domain of neilb@suse.de designates 195.135.223.130 as permitted sender) smtp.mailfrom=neilb@suse.de ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1708382745; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=jhVHfbYrXzhfXFBgvCaTvPo61AcJ2SJpQ0r3nOcOMWo=; b=RBqWpMZaXH1QeF01NtLBSidkhFNmaIi5H/mwJM1VymUQpUQ9mxPXUky0UprVnB1lYMLwFr yEgkfKLk1vm5c/IS6ZueFenze8Mq9xjfwmBLhrmiUJbq3LM1nUbDDQjPyoIm8CvL/ASHXe /CJYC5MbPK2ZZX16lqm/zbSp/Laovx8= ARC-Authentication-Results: i=1; imf19.hostedemail.com; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=ffBLsxdk; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=qSDppZHj; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=ffBLsxdk; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=qSDppZHj; dmarc=pass (policy=none) header.from=suse.de; spf=pass (imf19.hostedemail.com: domain of neilb@suse.de designates 195.135.223.130 as permitted sender) smtp.mailfrom=neilb@suse.de ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1708382745; a=rsa-sha256; cv=none; b=SgP4nCOpUIyY34y74Sy53HnTACcJK00E5nhyAFpIejwh+e/4twqqEuy4c6SZ80zdfQHUgh ATOUOrl650yYtIcITTEhJnsAxpAQtUiK2kE0fED236w1AZxRxJ4nmp69rbzLGZIldXWDjd Ko20oIBwV76vV2OzC4ooc88MYFiLNe4= Received: from imap1.dmz-prg2.suse.org (imap1.dmz-prg2.suse.org [10.150.64.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by smtp-out1.suse.de (Postfix) with ESMTPS id B8E85220C1; Mon, 19 Feb 2024 22:45:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1708382742; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=jhVHfbYrXzhfXFBgvCaTvPo61AcJ2SJpQ0r3nOcOMWo=; b=ffBLsxdkxs2Vl2iAehHqNwc/J/goXUBfsvO3BNlP2NGTF1DhODsMjvGv1o/JZf/aFhBx7k jsDKJmnyATkUa2KxIqRua8yDpw/ferwWezTZN1hzjjbcnHgUbPW4jmp9J4fypF+b/rRs6/ w1WN/hkgkKf3ys8LyQqTkzAanKcx7HU= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1708382742; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=jhVHfbYrXzhfXFBgvCaTvPo61AcJ2SJpQ0r3nOcOMWo=; b=qSDppZHj9xv7ph4gNovDdeF0vGhlKJd4Cwy3Dz0LIkby7qqEPkEO+ZjfJ1aqKVFqPl7cCc zcV8tkGZfhuNHcDg== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1708382742; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=jhVHfbYrXzhfXFBgvCaTvPo61AcJ2SJpQ0r3nOcOMWo=; b=ffBLsxdkxs2Vl2iAehHqNwc/J/goXUBfsvO3BNlP2NGTF1DhODsMjvGv1o/JZf/aFhBx7k jsDKJmnyATkUa2KxIqRua8yDpw/ferwWezTZN1hzjjbcnHgUbPW4jmp9J4fypF+b/rRs6/ w1WN/hkgkKf3ys8LyQqTkzAanKcx7HU= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1708382742; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=jhVHfbYrXzhfXFBgvCaTvPo61AcJ2SJpQ0r3nOcOMWo=; b=qSDppZHj9xv7ph4gNovDdeF0vGhlKJd4Cwy3Dz0LIkby7qqEPkEO+ZjfJ1aqKVFqPl7cCc zcV8tkGZfhuNHcDg== Received: from imap1.dmz-prg2.suse.org (localhost [127.0.0.1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by imap1.dmz-prg2.suse.org (Postfix) with ESMTPS id 784A8139D0; Mon, 19 Feb 2024 22:45:39 +0000 (UTC) Received: from dovecot-director2.suse.de ([10.150.64.162]) by imap1.dmz-prg2.suse.org with ESMTPSA id khfXCxPa02ULVQAAD6G6ig (envelope-from ); Mon, 19 Feb 2024 22:45:39 +0000 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 From: "NeilBrown" To: "Matthew Wilcox" Cc: "Mike Rapoport" , lsf-pc@lists.linux-foundation.org, linux-fsdevel@vger.kernel.org, linux-mm@kvack.org, linux-block@vger.kernel.org, linux-ide@vger.kernel.org, linux-scsi@vger.kernel.org, linux-nvme@lists.infradead.org, bpf@vger.kernel.org Subject: Re: [LSF/MM/BPF TOPIC] Reclaiming & documenting page flags In-reply-to: References: , , , , Date: Tue, 20 Feb 2024 09:45:36 +1100 Message-id: <170838273655.1530.946393725104206593@noble.neil.brown.name> X-Rspamd-Queue-Id: 7FE131A0017 X-Rspam-User: X-Rspamd-Server: rspam05 X-Stat-Signature: czyfuqbimze6ayajx54sj4rc7oeww1t8 X-HE-Tag: 1708382744-739679 X-HE-Meta: U2FsdGVkX1+fzgjfaAaQ896Q64B8hU49fOrDKs0d5p0PqlDcjz3ScBkwlGO8nQEyGbxLxvp/rqgcd63rs/wuspS8YHSRc8XzB7uBbyFWZUSe7uwB6a2EzI1TUXQEMf/4hhrQRwVXi1O8tgJZgyrpW+scdAnG42OcvlypRwiUuZQxuTRbiNyncF+74ThuVkk88+5ntZ9+NsTxSkpt477pmJMdBUvcOiwCfLMgtuT8HeM2eMhMiDPa/+9Qn6xD+8yWOzDvRz7DSSuPr+kGwZXqPqBIeFZCABkifJMomtVLmcZj2Yel5QIt4I47TT3LKy//Vk9YC5kRp3DnzROVsCK+0PxJ7h23BLx291m6RpZ/c0+1N7DEeH7s2+/GYE5EN+I7m7fvjZW7cUmDihKh0sgwI9ZpsOlZTI3A6nwbGhYtTjc5H1UQpTJjKYZx8CsWDzlqSu9IZjeeCFd0A241DeZ9UP+oufpHAAzPICc6H5rrW2d0RicMCGUh1VFPrPwmo2ocxqatCBP75ywTDig/Fcv5+edXNDVa9PLOkvGZvG0BoBqtNWZTY8hYG2ty6Mo6yElkOkX1k2sezvV6U9TLCn6D76DRVyHl2O946kBcIJZ3I3WVhM4sSS7M/eI/h3/c61OLA2zL9h2UBROgudOB5zm9vprKbAdXTKRxuMxyrab01rUeblLoX9ZmTxGc26oLs000gok7uB7L5yxXSKGw3ts0JVDiuVK6EsW/9jmJ1JnL/nQOj3k3hFHEhj//ulM78g4vM7X26r/4GmffnosvzR07czeH4vYAmFieOgFWDY9M5jzEqib1+kGZi7rjtXAvgaYPwL8642WOCr6tO6b5TUM3+bLda8X1ZkousskXONHFp/+wZ2PDEX7e8aoQ6duruRfqWQgB/0J4GKut5g5X2khQMHHYZ9/0jN9AG8vIfixE1feVSd+pdWC5NyIE2K+wesMWvhO381hkNsgaoPou6FO onawa8Bh kTHPb4c1FlsMvqW4Z48T8pbnUsTcYqPinz9j8KaoARX6EdZisdqI3cqkFUhg8FI5brscVQN2jPRLgwt8JoaLscw54qzsGs8GS5q0LgKk2cvf2So2t/9BrKSzxZz2QDgSF8M9RLSCPYuXdsQBrF3UFTPnJPIK+f9uGW1xIYoRBDQeSGrraF4ObMFpDIScAylRAZi3aB/f4pTctY70= X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: On Tue, 20 Feb 2024, Matthew Wilcox wrote: > On Wed, Feb 07, 2024 at 05:51:44PM +0200, Mike Rapoport wrote: > > On Sun, Feb 04, 2024 at 09:34:01PM +0000, Matthew Wilcox wrote: > > > I'm doing my best to write documentation as I go. I think we're a bit > > > better off than we were last year. Do we have scripts to tell us which > > > public functions (ie EXPORT_SYMBOL and static inline functions in header > > > files) have kernel-doc? And could we run them against kernels from, sa= y, > > > April 2023, 2022, 2021, 2020, 2019 (and in two months against April 202= 4) > > > and see how we're doing in terms of percentage undocumented functions? > >=20 > > We didn't have such script, but it was easy to compare "grep > > EXPORT_SYMBOL\|static inline" with ".. c:function" in kernel-doc. > > We do improve slowly, but we are still below 50% with kernel-doc for > > EXPORT_SYMBOL functions and slightly above 10% for static inlines. >=20 > Thanks for doing this! Data is good ;-) >=20 > I just came across an interesting example of a function which I believe > should NOT have kernel-doc. But it should have documentation for why it > doesn't have kernel-doc! Any thoughts about how we might accomplish that? >=20 > The example is filemap_range_has_writeback(). It's EXPORT_SYMBOL_GPL() > and it's a helper function for filemap_range_needs_writeback(). > filemap_range_needs_writeback() has kernel-doc, but nobody should be > calling filemap_range_has_writeback() directly, so it shouldn't even > exist in the htmldocs. But we should have a comment on it saying > "Use filemap_range_needs_writeback(), don't use this", in case anyone > discovers it. And the existance of that comment should be enough to > tell our tools to not flag this as a function that needs kernel-doc. >=20 Don't we use a __prefix for internal stuff that shouldn't be used? NeilBrown