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 5E595C48BF8 for ; Mon, 19 Feb 2024 20:13:58 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id D395F8D0008; Mon, 19 Feb 2024 15:13:57 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id CC2DB8D0001; Mon, 19 Feb 2024 15:13:57 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id B63D98D0008; Mon, 19 Feb 2024 15:13:57 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0015.hostedemail.com [216.40.44.15]) by kanga.kvack.org (Postfix) with ESMTP id A09A08D0001 for ; Mon, 19 Feb 2024 15:13:57 -0500 (EST) Received: from smtpin23.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay03.hostedemail.com (Postfix) with ESMTP id 67333A0489 for ; Mon, 19 Feb 2024 20:13:57 +0000 (UTC) X-FDA: 81809654514.23.CD8FCFD Received: from casper.infradead.org (casper.infradead.org [90.155.50.34]) by imf14.hostedemail.com (Postfix) with ESMTP id F2A18100016 for ; Mon, 19 Feb 2024 20:13:50 +0000 (UTC) Authentication-Results: imf14.hostedemail.com; dkim=pass header.d=infradead.org header.s=casper.20170209 header.b=J3w1tZlH; dmarc=none; spf=none (imf14.hostedemail.com: domain of willy@infradead.org has no SPF policy when checking 90.155.50.34) smtp.mailfrom=willy@infradead.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1708373635; 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: in-reply-to:in-reply-to:references:references:dkim-signature; bh=Jchb+LZCv2qEJtD+Rt9qzwfdoWc+U+2jiOKWjU4NWow=; b=2ZRBiyZCrNzPraQYlNxlnIQdtLZVmT3UvovQynd26WYAEqm7grPBrX+APD6NkeT12gxZNx xfOveyo0e5UOKTa7czeHpkbfz+CB2fgq0zhSBCzwZX5hWBoXg2n+2EWlSc5mhTXIcd/zZB A7bwzeDZAQISXNzNRk+bIxP8noAW5EM= ARC-Authentication-Results: i=1; imf14.hostedemail.com; dkim=pass header.d=infradead.org header.s=casper.20170209 header.b=J3w1tZlH; dmarc=none; spf=none (imf14.hostedemail.com: domain of willy@infradead.org has no SPF policy when checking 90.155.50.34) smtp.mailfrom=willy@infradead.org ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1708373635; a=rsa-sha256; cv=none; b=FCZ2of3f+duEMWYvi8/2gJqdpruGWZTmQPgcFJ6BItmIR00YXQTfmXt8bPiFWr3T0d2Abm GVyQCY1xl8ITNh9ljRFTvbTNM91CyXKzTfOHJpWj9q0O1HqpmD1z1y+mAMvMY0DSWo8lid +PT4/T+etGGTO8WO2iKH3Ke5FGU8JnA= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=casper.20170209; h=In-Reply-To:Content-Type:MIME-Version: References:Message-ID:Subject:Cc:To:From:Date:Sender:Reply-To: Content-Transfer-Encoding:Content-ID:Content-Description; bh=Jchb+LZCv2qEJtD+Rt9qzwfdoWc+U+2jiOKWjU4NWow=; b=J3w1tZlHo7drwooqkjX3y5SPfH elaMwmvPoX1hmpg+4MB+cvamg309guKr/Ij2Y6t81FG4QQUXolrnW9AUb0SOp3+MK6Ie3VVQP3a+B 4qZ90X44sLH/lAnfmD3eeelqIMhkJOgeoLSevHh91GjJ5TmJfsDTNFaAKSCd23L28KzNUXaDcUunY HPTk5lWwmN0VUSVaPnhMxLoHcMDre1m70lSGojq4FjeyhUPbbSR9IKfD/GuJzTrpogXa4wracCW9z ZnjwkrluXe78+suPeKnfQquNV1HZkGZ9jbVhHpsSobEIXAOMuEZZgbrzezqoSfQhfvl4dUmSsYV28 ZmkmHbGA==; Received: from willy by casper.infradead.org with local (Exim 4.97.1 #2 (Red Hat Linux)) id 1rcA1I-0000000DgB5-1OL3; Mon, 19 Feb 2024 20:13:44 +0000 Date: Mon, 19 Feb 2024 20:13:44 +0000 From: Matthew Wilcox To: Mike Rapoport Cc: 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 Message-ID: References: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: X-Rspam-User: X-Stat-Signature: ydg7m5kbxgq47urtjcj4pagon719bmj6 X-Rspamd-Server: rspam07 X-Rspamd-Queue-Id: F2A18100016 X-HE-Tag: 1708373630-227760 X-HE-Meta: U2FsdGVkX18YczEFyG4SD7VWVQFb+9wqu9imxI9Q/0KIRS06p61RKV4UXSe1SA/F0lZIXbt1zMrirbk7xJcxCiyyp+K/GdPGBR3uImsaR+tm4mf2KhTlv99BQHcaCmXEEzM80AskRpzxuQ7om7E/lxMUQ8krarZo2iqR2sQmqNaFzQMiwA7z8wGQqai0ISV4r+0mzYcJX8W6VDSvqcSAuU8d1vKjIyvHi0raORLGn5pgCBb/1/hPAzwbU1MZLy6wtRhEgZcjhsMtBDPNqaypxPsiZV4j7qP1cOcdHi1WzredOXqJWCO1Ug5v3cGKo6NmG2IQ2Soi254AZGIbfP3SRQUFQ56F866ufCnyV2J1MYRd5Kwxq4omHEO8JPJbQSU/CgV7FJ5TmNiCC84VzOPhVjRK40mY6QsCh3sFReKLf9rwgulQbkQWE2tVBrjjMtTDGtn24JKZmQD8HVyE/X25LDGGtciJCYdvsr77oQifMriZwLCBVdxDQQnBVWxdljTukrapvVgy1NjW5lgLm7gxD5l0TIoYKkbhvnckbERhTfzCVdqtEk2CIoafgHyRWMvn/52CS5Iw9TGM+kCVRgje0t+pEXiL6zjLvxUJM1pbqHrNdXdBdNfp2ItthEXGfqz5/vqsChuZP31q42LlKJP6pc42DzSaY60ybfbdaHJwM2t2Gie4yzQfLRdE6W5L+ki/Ggy0eMHgtbR6lVxDllIsxntLeuLxGhO/tH8lcy0vXMONmhPiqEZH6AEaCYTvAXiM44Yof3Y5jv8ZYIdb2ipFEnq3dJ4fthrfmO/S2TTnA3tlT0piTzZL0PG4HAZxozuesx8HfjwilvG8O93aUi9e6E1t7HWpJnqToL+Ijb6lLOXI41xpD8043+uSzQjJqmbzIPewPtcv9tTpuODnVamQer1Y4QiIFRoAbFtze0FnzE6X3HdMSe2r5dBvkt9IO561FBn26oA/KlzLY/sdc62 6UWfDtGi xT1OIFXD1fMiMKYkSf6iKu8ZkDRchpxAA6Xjy55yqtCxF4rFHdkZcp7KDOszjksoRK0fQKPzcykA35cSbqabWusN47yI5AofhVIy84z+x8yv/Zot3/0anqqV7o1g6ii07z6cQJMDGZJC6z0s= 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 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, say, > > April 2023, 2022, 2021, 2020, 2019 (and in two months against April 2024) > > and see how we're doing in terms of percentage undocumented functions? > > 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. Thanks for doing this! Data is good ;-) 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? 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.