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 86999C5AD49 for ; Tue, 3 Jun 2025 14:34:00 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 233876B0488; Tue, 3 Jun 2025 10:34:00 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 1E2CB6B048A; Tue, 3 Jun 2025 10:34:00 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 0F8B26B048B; Tue, 3 Jun 2025 10:34:00 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0017.hostedemail.com [216.40.44.17]) by kanga.kvack.org (Postfix) with ESMTP id E43DA6B0488 for ; Tue, 3 Jun 2025 10:33:59 -0400 (EDT) Received: from smtpin06.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay01.hostedemail.com (Postfix) with ESMTP id 8AE491D6A87 for ; Tue, 3 Jun 2025 14:33:59 +0000 (UTC) X-FDA: 83514333798.06.8B68B30 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by imf18.hostedemail.com (Postfix) with ESMTP id CD5C01C0016 for ; Tue, 3 Jun 2025 14:33:57 +0000 (UTC) Authentication-Results: imf18.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=bjuvxdBO; spf=pass (imf18.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net; dmarc=pass (policy=none) header.from=lwn.net ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1748961237; 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=xuzJ6pVHRkOA6mC6eSB047dEohJN/pd9soeYCZQRrNY=; b=10q7rL6O1oYHc6LC8o/0+Np0NYnsW5H+3jBroLaOlsu811eIikqpKSujgovER2hsu14wS3 sYd9X8j19SonnMDtjs0w5DBEUmGaQ4kgQ7fSZUKO8ix/AReg+TsF2Hzw//0SXqa82J0wbN RaF6+OTcu/8C3CKiJ0lB6EGH7gBzWQ8= ARC-Authentication-Results: i=1; imf18.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=bjuvxdBO; spf=pass (imf18.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net; dmarc=pass (policy=none) header.from=lwn.net ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1748961237; a=rsa-sha256; cv=none; b=v1xdzHIuBLglzQ3GoPP2VH4LfSR1TW8d5tk5i1ezpftM4OKxmgdFs+ib0KNiOwY+Lni7Xo 38Qsxd0WfLsafcOHsspYkUJxgki/LU0C7i3nxVbV/OKHmecf1KSJ0j4wURyn0H7zjEvmJ+ 6nxR5VhQE1zUpvcWQZqsNWiLIuTl/6Y= DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 2C74141ED0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1748961236; bh=xuzJ6pVHRkOA6mC6eSB047dEohJN/pd9soeYCZQRrNY=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=bjuvxdBOkFWFGc9lPwDAFgGPB1xqaSZmxICh+WhRoqYTpFzqQ3UsZtYRwl1o7W3XQ 1v09x5i1ajdt//pT9RuhWYc07eOq4VHR3IyVj2yrMi0V7GISj/1ScS2DBt5LzSV+xA PhUR6ddS3kXbntmYGyH8Dih6G/UZb+FnrM8YF9eOT/BFNx2ixsOydPxunVxvNw/2x4 2pZy6hU8gIkML3r7FPR4YANeqSzl4gwELRxATwefXtl2phZVdRu1yc0U1QMzTHEmqD u0ux7dcw8WXFX/+g6iDKHp2r6ecGLcx5Rk7gQJDGwy0HmBce7QdC9szyGV5aaF+CRI O3Dduxgjs/8Ag== Received: from localhost (unknown [IPv6:2601:280:4600:2da9::1fe]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id 2C74141ED0; Tue, 3 Jun 2025 14:33:56 +0000 (UTC) From: Jonathan Corbet To: Lorenzo Stoakes Cc: Andrew Morton , Suren Baghdasaryan , "Liam R . Howlett" , Vlastimil Babka , Shakeel Butt , Jann Horn , Qi Zheng , linux-mm@kvack.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [PATCH] docs/mm: expand vma doc to highlight pte freeing, non-vma traversal In-Reply-To: <28f53f7e-5ac2-4ef4-8944-6741161e6870@lucifer.local> References: <20250602210710.106159-1-lorenzo.stoakes@oracle.com> <87bjr59634.fsf@trenco.lwn.net> <9fc9ac50-abce-48bd-979f-2e00b26917b5@lucifer.local> <38bcf562-86dc-42b2-9ffc-53cbc5d8ac22@lucifer.local> <877c1s9b6p.fsf@trenco.lwn.net> <28f53f7e-5ac2-4ef4-8944-6741161e6870@lucifer.local> Date: Tue, 03 Jun 2025 08:33:55 -0600 Message-ID: <87y0u87v3g.fsf@trenco.lwn.net> MIME-Version: 1.0 Content-Type: text/plain X-Rspamd-Server: rspam03 X-Rspamd-Queue-Id: CD5C01C0016 X-Stat-Signature: yeose9wat8taxk6edm6jtb9i65cp5dfm X-Rspam-User: X-HE-Tag: 1748961237-125248 X-HE-Meta: U2FsdGVkX18ZS5wI4MZHRT97zRhBXBkl2mxS1FI4S+NEfmrpMNDij+2d2yGvPGFj9Vyhwdyq48PfC75OBCGe9o/rufqTfz4H1wJv4hej0hoWBPlcUb0LOKLnPb403CCfRYo+uIZPLQIvqlB3qf1p1xEUaEEIeSYuFCzZ+IRbuxlAZ4uZlDgr1r5NYtfH3FbagA3imxY320IrXK5WPRKdFdhlg+iHDlOvXmqhblULp7nq/PRpbNvjn0dLt9p0PxE8nEwFOM43VO2wB8czw3KDnjzMFhOOKU2QllHLf1t5p4dlt5Aky7EjfNGfogQWEIseoMhcI5Qj6gr8SAs+j/k9sKOWetfmUnoTOeaYOCZ62IQOVncgCmIVtobLu7W+/cOG6Icm95IaFx+ns1qm+95WXF/q35qavKn2/wpuXN/DyDGsjCyzuppOcSkX2Um++MJxZQPT6g6UKB0pmTCDU+7Dpc5DKqUHz6/GoQeigzPgbz9v4jG7SIdAdeL+/mASSq0MPNZW2lWmV9V5N5H80Xy32J32Kepnv3+GWWcXwv0BUddy+x4XyPBkpJKCCbl+eQCTb+pUEaXqNcwUPAYQ9oq7H0HEbYsDZp04XmBj6EDKwikymhLnUbbWeU8hQU5rPjcuhZeyKCslOGvfkJXgKrMrLEtQgVSgIuiR086WhA+YdJfjS+JpD7Zb1aKa6/tDqrwuLjBOyc/IlLceNcvEoXOAIxHOzNmtr+etCNsaqXblg17g1u6roErTSQv+y9QVivzounA1L9Qot5kBIrdoNeQ9FLFu1lByrlsm9Da+5BbrKgGFgTFqSqDs8vMlIDOoccJ1QCYqhynNymxA9qvkFAcYK93oDR2iIpFFyiwgI4NbxoDV4yDtlB7/cZQhh2izdIvfFB68dg+KZlbhCR+KqJxb/CY/fsXotxLWhmFHa2iI5MJmy90t/PsnrhLfH/LJXhXClDtKOee99VHrWkjk4DM FB7xqW44 xs6S+W/vDSQWZsVMYWvAAR8XkUqAg818nQATyW5MCwjGm64BD8XbKQYhcKBjnnHsm1gJlSuXqD6WnhoaIoZUP5GrWLfoeMqYUhBdI3QvU0H//GiXix0BO3FXAsubSeT3D8itPIw+KxdXDi1seTbwTVOeODnL6HdKxGvMqdFVCaKUZHlJBY2O+axilYLHopioO8GgirnSRL+1XZBHCLfSLTBYZq+atapzylwcXz72JJyvZpXH1lk8Cr1G8m/AisLT2A1oCNUpylFiOBczyKl6q0hOAvq4e0MTHaTvzu7c0ljb32So1ASClfdV3RQ== 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: Lorenzo Stoakes writes: >> OK ... If you look at what's going on, some of the functions will be >> marked, others not. The difference is that there is no markup for >> functions where a cross-reference cannot be made (because they are >> undocumented). >> >> We could easily change the automarkup code to always do the markup; the >> problem with that (which is also a problem with the existing markup >> under Documentation/mm) is you'll have rendered text that looks like a >> cross-reference link, but which is not. We also lose a clue as to which >> functions are still in need of documentation. > > Isn't it a pretty egregious requirement to require documentation of every > referenced function? > > I mean if that were a known requirement I'd simply not have written this > document at all, frankly. Who said anything about it being a requirement? I think we have gone way off track here. Certainly it would be *nice* to have all of that stuff documented, and I think there is value in giving a visual clue for stuff that lacks documentation, but I never said anything about requirements. >> The right answer might be to mark them up differently, I guess. > > But... what I'm doing here, and what mm does elsewhere works perfectly fine? Why > do we need something new? Because you're thinking in terms of the rendered docs, and not the people who read the plain text. "function()" is far more readable than ":c:func:`!function()`", don't you agree? And rather easier to write as well. > Surely this cross-referencing stuff is more useful for API documentation > that explicitly intends to describe functions like this? The cross-referencing is *to* the API documentation. Again, you are mentioning a function, why would you *not* want to let the system automatically link to that function's documentation? Especially since you're using markup that is explicitly provided for exactly that purpose? Does the link cause some sort of harm? Thanks, jon