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 B3973C5AE59 for ; Tue, 3 Jun 2025 14:01:09 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 12D0C6B03AD; Tue, 3 Jun 2025 10:01:09 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 0DE6A6B03C8; Tue, 3 Jun 2025 10:01:09 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id F0F6C6B03CA; Tue, 3 Jun 2025 10:01:08 -0400 (EDT) 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 CF9D56B03AD for ; Tue, 3 Jun 2025 10:01:08 -0400 (EDT) Received: from smtpin15.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay07.hostedemail.com (Postfix) with ESMTP id C5254160A27 for ; Tue, 3 Jun 2025 14:01:07 +0000 (UTC) X-FDA: 83514250974.15.BC03B53 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by imf22.hostedemail.com (Postfix) with ESMTP id 7EF1EC0023 for ; Tue, 3 Jun 2025 14:01:05 +0000 (UTC) Authentication-Results: imf22.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b="F93Y/bpn"; spf=pass (imf22.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=1748959265; 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=uOyNUmXYmGjvQ8M6ifu04w16RP5byp/ebrZPnuwV0QI=; b=i6xC8l7lZDAR3lCackvnT3E1ImuYANF5c2r3fmQIr85iZMTh0uRR14+viPXDmRzPSvu/+h g4Q+BWhVf8RiBhnXvSZyx4W7tsoUwSSb7pkfENRjvKKYZsveG0zoDp2a/gIcKeDRKT1vpR 8M7NVUzJMKj3nZGZdZXAX+SDV9L68Q0= ARC-Authentication-Results: i=1; imf22.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b="F93Y/bpn"; spf=pass (imf22.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=1748959265; a=rsa-sha256; cv=none; b=GkUziwgi9F2wPVC3adFJbSax4BI16BHg1gK67d+7y3XqX0DQnVNix95l+S29PYuUy9LyQH ZFCx17fkTX7+/sPq3QbFjrKL6DVhqp31DaONE9k75beS2xEJgqFGcp7DLebHYeAMjNTqtR CkVBhKrJ9hQaUrV9LSYJ7zpIJVzLxLc= DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net D571F41ED0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1748959264; bh=uOyNUmXYmGjvQ8M6ifu04w16RP5byp/ebrZPnuwV0QI=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=F93Y/bpnWL4BxMcfbzMXUVjpLlzjzDrdmpEj/FZcpS9d4LazP5I/V92Hk4Szna1V3 oL+bMlZ23kHsdrqVWowvjQ4inyGrUdMx7zW5xTEk/vkdPDqtokWvtsF+gmUwSJ7wzo CEov2CzSe1ze2h8J20GaTId8iIPX03ApU5Xjtu+vpn2ytirpqW5zmeYaixQ12QHMrA Xz8Xryed0VVyuXRE4HVBlLyV2g/612fqFqLTGPx1O/TmdfZUh8q6I0J+9p1SaA2mdE qQo9LX4IhKUfmkBq8Du6hLSrdorBvfNM4EA1BqjXSoO1WWfDxcDmrtcymOpUPGLGVO N3L1EbKYrSTdg== 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 D571F41ED0; Tue, 3 Jun 2025 14:01:03 +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: <38bcf562-86dc-42b2-9ffc-53cbc5d8ac22@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> Date: Tue, 03 Jun 2025 08:01:02 -0600 Message-ID: <877c1s9b6p.fsf@trenco.lwn.net> MIME-Version: 1.0 Content-Type: text/plain X-Rspamd-Queue-Id: 7EF1EC0023 X-Stat-Signature: 48cob71n3etbgng9hs84zuz3rnij47bt X-Rspam-User: X-Rspamd-Server: rspam07 X-HE-Tag: 1748959265-869587 X-HE-Meta: U2FsdGVkX19fn3vhAXOaBeJL5aI0dtbpa2lyAoEpWZ8W3bhOP05SNuqQa+Zftm6u9hJmSVReNwqZkUfc6KDifO30zeeMifGJimoL7e5T/05wT8C1C98j5fxOkK9Z1/k6/RZ+ew7V7FuvWrxJK0QNsgNGlFW5SdSBmitXfWNqpWxxbVEOFcPyLZ4YkmDtzcZqnbkKdV8CiOXV5GxfeyLbnhMf5wJasxUAR0cDboQgSqbj+KMSPOdk+z4jqNpyF/AKKq785N5wScE+8mA7QPIcdmJ58RY4Eb4fdz41zhMVR3lMlxvzzDMaz3s36vS0XLg4QCvj3Y5Pc6DR2D8A3UJsDKmpK6jLlaDrGoJwpaxQy76ZMbyt0hnQUvrEdynP4+9g3gyi/Z+/9KOqT6a8A/MfbFZ+Lf0Z+kL5wYh7gWwWL0tCw8vjysogsHrgfUbw1unXVpQqPSGKlRG6YQta98T9l9smGxNcfdbfQ3Q4Zl7wXsUjHr3AhkQiYmSrwZOp/0Abp4JvPIbaLo+qzK9041gMes0+WClqNM328Bwplu/xC9OkJ9uQeZxFt/UuOl8q+Z77vgePwaLX7qE2h0uNAootl+7crM0NqodM6m567vvvS6mdEdANpuBqFYory9U3KpqOlqBRUTvi7z4uYpipVAIxzMc1oCQYb3PQ1BdXvSpZRMgEemhm29qX7oOlp/PZ7Y+Ziv9W9kCv85IsIHUwKd+0esCNkpI9zPOdwIod08ERmBvSUY8X5sAgE6Sou7NymKdPyrnL0YG/rhjkGszvm7d9vJ4dLGHgK4TGJhzP8UIShhAPvuCIGuP+pkucAt6rCIvGKh5Ls47sjKFRXe9uw0O8wV1Le/5lZjn2QD5jULQDEcGkAr6InSabBcHY//CMdcFWWJGBCf4zCzaD7G3eQwxYq/zHDNmb3y70UK6C3g9RW77IqndFnrNqD7+zualBsB6fqMoh4okGkiS3hP5Fyze 49dNGqGu ZQrNv1mL+VWBIhc3czYmqAKRQ/ZfDpurSUO1hvuJx8dSVRzfEmapQ+uz1zEjoIej8V9Y22RSLaf0GMFklEHkFbQPdoK1aWhUoFEkBrmu1TKV+RTrkf6qJslRI8VC1gd8g7xNHAVMgRW7YHd3PN1QE30k3saIQztppBj/QWsdifLJZEjO+JfD4YyYmIYpXY3m32KnEHOzba9eZyKYfqoSnHK82A52WS1e9PN7avDCdsw1K661zrcD7iLDaPvMTpfE8TK9Ow+xt0yOFE71sS27xztY+K+qKZTyEg2XLwMGeD7Zlej3nLmsNNXG7kQ== 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: >> Re: the c:func: stuff - >> >> Well, the right thing is making function + type names clearly discernable, and >> it just putting in the function name like that absolutely does not do the right >> thing in that respect. >> >> I feel strongly on this, as I've tried it both ways and it's a _really_ big >> difference in how readable the document is. >> >> I spent a lot of time trying to make it as readable as possible (given the >> complexity) so would really rather not do anything that would hurt that. >> > > Somebody told me that in _other_ .rst's, seemingly, it does figure out xxx() -> > function and highlights it like this. > > But for me, it does not... :) 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. The right answer might be to mark them up differently, I guess. jon