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 04BF6D5E380 for ; Sun, 10 Nov 2024 10:41:41 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 4FBB96B007B; Sun, 10 Nov 2024 05:41:41 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 4A7D26B0082; Sun, 10 Nov 2024 05:41:41 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 3962E6B0083; Sun, 10 Nov 2024 05:41:41 -0500 (EST) 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 1E4346B007B for ; Sun, 10 Nov 2024 05:41:41 -0500 (EST) Received: from smtpin02.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay04.hostedemail.com (Postfix) with ESMTP id A10141A10E5 for ; Sun, 10 Nov 2024 10:41:40 +0000 (UTC) X-FDA: 82769843940.02.63D2DB8 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by imf30.hostedemail.com (Postfix) with ESMTP id 3822A80005 for ; Sun, 10 Nov 2024 10:40:25 +0000 (UTC) Authentication-Results: imf30.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=JW8duPR4; spf=pass (imf30.hostedemail.com: domain of leon@kernel.org designates 139.178.84.217 as permitted sender) smtp.mailfrom=leon@kernel.org; dmarc=pass (policy=quarantine) header.from=kernel.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1731235246; 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=/Gwd2Wu8HDE9PbfNUGcA9BUrviVIn8ooIi4vutwOAE0=; b=kVkjuX5vsPuwiMfWbwAJ2V8dHcdWjfevODlMjjIPs35TbbN8Bo43r5ZdirqJVHG15V3Td8 DchiTrknTfYAhb2tKDsK1y7nfiSirIEcf17ygJT0RYIefIhikAb3Wf5jtkdXH1jA0lBIgV Vc8bflLoe7BrRD4+oi8ntibJgTBP1m0= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1731235246; a=rsa-sha256; cv=none; b=LFgERAlycUqrc8QkCIfN0+jE71LQs9KQS03/yXm+ZftLhce5erTuqZ+p95rGbucrmwpWa1 zdIlDjM6zDhUaBZDYHVW8kjUAbNKMC74j9GkMXtDaonYSpe5A3NmHFwrzL5yc+Mw+vVmYE /xeh6xtQrQGws8s8v7TaxsekVxQx6/w= ARC-Authentication-Results: i=1; imf30.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=JW8duPR4; spf=pass (imf30.hostedemail.com: domain of leon@kernel.org designates 139.178.84.217 as permitted sender) smtp.mailfrom=leon@kernel.org; dmarc=pass (policy=quarantine) header.from=kernel.org Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by dfw.source.kernel.org (Postfix) with ESMTP id 6235E5C2982; Sun, 10 Nov 2024 10:40:53 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 6A12DC4CECD; Sun, 10 Nov 2024 10:41:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1731235297; bh=KJTVz52sJu2oQj0BOPzh46r/ng+VWSz4cJfy6f2DTow=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=JW8duPR4zgtshHYsGnyTHtlzUbI9C7VSu6DKWCkFGrApkoWJWSxhGLCw5xgUraK37 KyNCPb36UhLBki49PXkqcD2sBnsPb3pSEYoDPi+P4LFHLRa96gSHPosI6C7dqbYMip vIVxA0qXAzTZEbJq1b7ufQuqLIfu45BQHuHyL9EX1PQY+YtgJ833g0BRQjd7iEAg3m WndbNLaXlStjkG2lTw6sbX+1iBBO11XE41go4jd7Z15Ik1RN38Prs+eyzYb42sG812 MOTUu7mg3HBNZVbtRKgzK0VBiDj1HOzE5fnpSg4ms0Wa3VJ7O+NYsKsaWDPF/fo35+ lxhrXIwkV8nJA== Date: Sun, 10 Nov 2024 12:41:30 +0200 From: Leon Romanovsky To: Jonathan Corbet Cc: Jens Axboe , Jason Gunthorpe , Robin Murphy , Joerg Roedel , Will Deacon , Christoph Hellwig , Sagi Grimberg , Keith Busch , Bjorn Helgaas , Logan Gunthorpe , Yishai Hadas , Shameer Kolothum , Kevin Tian , Alex Williamson , Marek Szyprowski , =?iso-8859-1?B?Suly9G1l?= Glisse , Andrew Morton , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-block@vger.kernel.org, linux-rdma@vger.kernel.org, iommu@lists.linux.dev, linux-nvme@lists.infradead.org, linux-pci@vger.kernel.org, kvm@vger.kernel.org, linux-mm@kvack.org Subject: Re: [PATCH v1 09/17] docs: core-api: document the IOVA-based API Message-ID: <20241110104130.GA19265@unreal> References: <881ef0bcf9aa971e995fbdd00776c5140a7b5b3d.1730298502.git.leon@kernel.org> <87ttchwmde.fsf@trenco.lwn.net> <20241108200355.GC189042@unreal> <87h68hwkk8.fsf@trenco.lwn.net> <20241108202736.GD189042@unreal> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20241108202736.GD189042@unreal> X-Stat-Signature: 6gygzb47569cce77hom68gdr4yxm13tc X-Rspam-User: X-Rspamd-Queue-Id: 3822A80005 X-Rspamd-Server: rspam02 X-HE-Tag: 1731235225-703231 X-HE-Meta: U2FsdGVkX1+3ldmvHxo4CFfvHI+Fuu7xfJ8stiYTrZQA7UhOfQ1sC5RMzZoYSLVlETm6r731zGBS21uHMYaU2SRQATZRmZcWsNZtMMDmoXX2RY38VxifA35ffAfkb0GM+sGOnU5mC8N2sNUlClDhG1YKAostEOWn19YuC+UtYJOx84oVw3xYGz4qfNumyKmofHR2Vl9xmYWGCsb9ushBdZoAiwgONSHznbjz046PVDfWVg0gUr7M0+b9vgcM14P5ZeBCevk+R6UedpKJBdpsM6lqA4SVIzMDpVqeIOPqnbO36Ez9CRWmr4S0WKNNMnen1FyrKU0EUCczqV+1QT5r0QCIm6Z9vxhr0HiFpLZCWAHHG18hjUVnHgNKCdyLIRcwXzH+GmjbEM/Kieo8cbTGOgmRslDye0BjJHbRansJko0XcmfSjZYjOquz3znN19Mw9ozJjmUmJrWdWBkNBOzb5Q096ycOWDV2DzHABl80FolOyiB5dPjkZTokPUaSKtu5Rff+ljmACUvGf484OA/CLk/c5EzbAYM/T2PB1NocKLpovhZnCGPjVCgZVellU8AHx19C1nXSbzR1z7+U63pKiNAipzFGHc06OjO0JuQn5oX2ErTWvNjRHRHX4OlLLe6JKf9xGY88DL7K50LZ/1ITt7IdKxvOs6c5BwTsXIKeb8hPsg0dJqTjpn/RQXNgEzvSKiW+WS6jEUAAiNEBtEDVxNo6BO6S7c05NE5+X/D0cNZlnTiHafhrgfChfNMuZV1Ue1wsNsUHSszcCW8GSY4/IXNFDWTbJjmaOxx+AKpmhv3uKdE1auad1gXL14AbwKfxeYpnhk/lafpXhuhKqXMDqmXb6jKV/IsPqvKBL2Z72Hy6wgVxFl93rviNoJFzc3TouJ3prPhIHeCBGJTW48ArA40fEirJzYdWYjhqi8nm8wUhXf6aS5NuK9WzpstnbTw2YM1PoQz9ZF4BBH93QlX kwZdwVZW HB7eD1PtJaiNHiwxgQb/I5EyO4ug/mEkaOTAal568b1MrC/9pW36JA3Cq6ewzvZud5HJqJfrXyPXLk2LuailXwf5zk/R5Xs9KCi+o3N6buEmWTzfH94jslWe7yQJDO4WyKe3i74CryREh7YxVBEOJeXEAxaHeP0OhgUqO4ouo5Ejy9/QCFhFm7XmDXRtcWiyfcIEEucjWdlalA3vwBSz9aPkW2CF6bbQnxEW9qc4iRnPKmY9S/rQjn/PQAe1quxsmOi5BKD8tWXFoSNxh33CWNXwrjQ== 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 Fri, Nov 08, 2024 at 10:27:36PM +0200, Leon Romanovsky wrote: > On Fri, Nov 08, 2024 at 01:13:27PM -0700, Jonathan Corbet wrote: > > Leon Romanovsky writes: > > > > >> So, I see that you have nice kernel-doc comments for these; why not just > > >> pull them in here with a kernel-doc directive rather than duplicating > > >> the information? > > > > > > Can I you please point me to commit/lore link/documentation with example > > > of such directive and I will do it? > > > > Documentation/doc-guide/kernel-doc.rst has all the information you need. > > It could be as simple as replacing your inline descriptions with: > > > > .. kernel-doc:: drivers/iommu/dma-iommu.c > > :export: > > > > That will pull in documentation for other, unrelated functions, though; > > assuming you don't want those, something like: > > > > .. kernel-doc:: drivers/iommu/dma-iommu.c > > :identifiers: dma_iova_try_alloc dma_iova_free ... > > > > Then do a docs build and see the nice results you get :) > > Thanks for the explanation, will change it. Jonathan, I tried this today and the output (HTML) in the new section looks so different from the rest of dma-api.rst that I lean to leave the current doc implementation as is. Thanks > > > > > Thanks, > > > > jon >