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 BCDE6C5AD49 for ; Tue, 3 Jun 2025 14:37:28 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 5BAF46B048C; Tue, 3 Jun 2025 10:37:28 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 597DE6B048E; Tue, 3 Jun 2025 10:37:28 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 4CF6B6B048F; Tue, 3 Jun 2025 10:37:28 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0016.hostedemail.com [216.40.44.16]) by kanga.kvack.org (Postfix) with ESMTP id 2AE056B048C for ; Tue, 3 Jun 2025 10:37:28 -0400 (EDT) Received: from smtpin10.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay02.hostedemail.com (Postfix) with ESMTP id 8A7A5120BB5 for ; Tue, 3 Jun 2025 14:37:27 +0000 (UTC) X-FDA: 83514342534.10.A68A8F7 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by imf13.hostedemail.com (Postfix) with ESMTP id DB8752000A for ; Tue, 3 Jun 2025 14:37:25 +0000 (UTC) Authentication-Results: imf13.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b="Fzyv0y/d"; spf=pass (imf13.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=1748961446; 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=uw373KZqTxfYc7CgajAJm0hoPspIDINCwb6qNNb/b2c=; b=JeV1OY88bLZSmt8gPQAhCT2OgLeIlAtNalD79Xe9rahjfD8XY3NRGA51Tn4A5CRQ1EyLjE /8876yN5a/rXLA+7unQjFp5z7Wz3OKe1vj1lsmCPHn2J5LMlZPpA1wCiIp0wxGAd8mfGZS aQZz+WGIK78UtPacQoFm0K1itOv7S5g= ARC-Authentication-Results: i=1; imf13.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b="Fzyv0y/d"; spf=pass (imf13.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=1748961446; a=rsa-sha256; cv=none; b=UljOqphl4DOosJIQn7G1Vd9peSyIOiy0iGia+FxUU6LWmk0ieLGh2eqWn9SEq4ukIBz9Zt RQtyN2a/zG3u9fdejF2TsHhNXPeE4y8uMyrwfkyK4l4GZhJ3z14yD74QMXnvBYMZZO00Ib UMF/NjMT638VtDTmeYLK5aZJZmtkCRc= DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 3756041ED0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1748961444; bh=uw373KZqTxfYc7CgajAJm0hoPspIDINCwb6qNNb/b2c=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=Fzyv0y/daizC+CqsktU1eYw3qfqwRekvSQTdxZWnPgVQ4dTTO45tBy2VxZug9voGr Vo2Oc2sPdIN9zD5H+wA1J8Zt7YjVSyTITU8TAXH4C7QrclLYAz33xAUuYXcSFvmxVb yHGKsmXe4Ce58i9tfK01pZaqc3xTntavvgxWpKnZJsjNFZl0VKGvD4f8PdE539GgZY RNGyEkQq4byV+byRM3wi4I/y9GJ4N3irjin11LWZduBaBEd5sft2tN/Cd/RAcuwp6U ULdlp9Q1VSJq7HVGoS1AHAtbYUIiq6RSv9mmTHnQ8nWtITi1Gf0bdX84WDdy2LclZQ 4NyKT8ktuA/SA== 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 3756041ED0; Tue, 3 Jun 2025 14:37:24 +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: References: <20250602210710.106159-1-lorenzo.stoakes@oracle.com> <87bjr59634.fsf@trenco.lwn.net> <9fc9ac50-abce-48bd-979f-2e00b26917b5@lucifer.local> <8734cg9auh.fsf@trenco.lwn.net> Date: Tue, 03 Jun 2025 08:37:23 -0600 Message-ID: <87tt4w7uxo.fsf@trenco.lwn.net> MIME-Version: 1.0 Content-Type: text/plain X-Stat-Signature: hdn7gq1w981y6f5n3xiexmwwemtuty58 X-Rspamd-Queue-Id: DB8752000A X-Rspam-User: X-Rspamd-Server: rspam02 X-HE-Tag: 1748961445-876532 X-HE-Meta: U2FsdGVkX1/GT4uekN88O4LuBI/CGp3HdIetVwTLdmnt8iYlqJlMe9/5SV9ReP+m+Dzh/eXTPp3XGpDmecyq38VcE3bp/F7cuLDbxA2wlTuMYdOTrTf/WRIIFcd/5h/LSgAxZB/9+8X7pFB5Y0MpvNg/EbwjOqiQ3tl+N5BsN6p/0FL1hCfgK1/TBeFJtcXpZg8kw+CGlVM6VAvD/ivTodLw/yf73fDbZ8gaMIdFUgQzFvx4UabmpWu5oDXjlx1VlWfFxbBll4QKFKLl/ZllN6DP/LTyXETxcNt+w1fKxNW2pyOZAzKn79S+pMljvAPUCN8KedLj5Uz5Fx6+L+JjUkd4nNyB0K+12mhpQb2sNvOvqmrcAoZhrlMIaSVfhhC6Sa8tCBJwYhXUvS/tlPpxOHWvss6c8Wz5rLGzAsEpFWo3RLQW+GWF2N5am4hT/bS0dEQRSY34AGa2lCIwUfDZc7WFBYlv434JDNQ8pBtWMwOSWb9ODHZyMiNuCHQivhp8lkexAG+GgJlfYjP9l5t+kgzyZp/z//SQdCbxcUBwEJDiGz2vjHdRkVJltF7a5R4lWcWImkO2Nc7YmkcPLvFAUm5o1hvInZy3324Fm8kSjcLuVWVGyMGQATXNptyRf7mOJBkhvJUILxIISzkMkcQxUtSP0EyS1xxdsIVKBSWrv0m4HELqkt0Ff1VsonOrpwRXHMLCf51H4fkFUp2V81yhBoyCx1lHroYG685gMshdZ+9nuTC8WcHJsD9Xk2qduxhwqJ41sIHNbktpYSCeOk54iP5tbM3IEQctqVXWLNTmG3JpUqsacjgoCD0/Zx5Ph7rorw9TNJvFdb71Si23PY0pmVUVPSc8lCHeqW85uvnVud51Gr0pImncdlRoA1z2lS1jlG1M+uNfbvjNci8MtsS+ZzewubqubPjh0Dt5tIKtPj/zeUNRnucWz/eF1ZKaEeMZNBryP0upOIxN5Z1B9J5 NuF7mR7R HJYyC+sjUt+hozzB1vXJpMEWkQYCz+2xym9OEEfB1yaBJpx7pOVMZ2lMKoxCwteCgUnwHsXE4YRcT1TtLzhtNOuZHnr8ghxwhO3puXOtHu/Lb0RVKriWnb9YxKg5PkndeZ2t00HpK/68Btr0pSRMiPCuzVHD63gtVmUerNEz8lZk7qj++coZjImaIGGJbJMSgILPeL2RHKpYUsTnbjs/RYIi/inwlIOAKYNC7mrpyl9wfyC6m6B9VTcUN1z3q8tvmkgWHOM/iLkxVM4iToc7pOEYdaiXAt/KmRna5RZENYwmBWCGAgN1zqcpw3w== 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: > But to repeat - 'given C's weirdness with typing I really prefer to be > explicit in referencing a struct vs. e.g. a typedef.' ...and I think that makes perfect sense. >> Why would you *not* want to cross-reference something and make life easier >> for your reader? > > Because it apparently requires me to document every function I reference? > Unless I'm missing something? > > I may be misunderstanding you. > > If not then fine, I can delay this patch, go off and do a 'cleanup' patch > first, that will drop the '!'s and come back to this. > > But if I need to document every referenced function that just isn't > feasible for me with my current workload. > > Please clarify! Hopefully I already have - I'm in no position to enforce such a requirement, even if I thought it would be a good thing -- and I don't. It's hard enough to get documentation written as it is, I certainly don't want to make it harder. My suggestion would be: proceed with your changes for now, it was never my purpose to put obstacles there. I'll look at having automarkup do something a bit more useful for references that lack documentation, then maybe I'll do a cleanup pass on some of the mm docs if nobody else gets there first. Thanks, jon