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 6D1F8D64085 for ; Fri, 8 Nov 2024 20:13:42 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 058746B00C7; Fri, 8 Nov 2024 15:13:42 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id F23546B00C9; Fri, 8 Nov 2024 15:13:41 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id D9CBE6B00CA; Fri, 8 Nov 2024 15:13: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 AC54E6B00C7 for ; Fri, 8 Nov 2024 15:13:41 -0500 (EST) Received: from smtpin02.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay01.hostedemail.com (Postfix) with ESMTP id 3A4981C6B40 for ; Fri, 8 Nov 2024 20:13:41 +0000 (UTC) X-FDA: 82764027822.02.21A4791 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by imf12.hostedemail.com (Postfix) with ESMTP id AD46540008 for ; Fri, 8 Nov 2024 20:13:22 +0000 (UTC) Authentication-Results: imf12.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=SGj7NgT5; dmarc=pass (policy=none) header.from=lwn.net; spf=pass (imf12.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1731096734; 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=SdL8Q8EQQQJJ8xM8160z/ZDZmIkZmULZbC6xpHvhB2g=; b=NME0DZwip2e/2Fy9jOomsXN/vUE9iNSUb7TvbLu7pg6st5Q5/ORMiWeXN+9WptmAfSqbWh kOkNQ82RSYPtoalHcWuv73Xar8HsEi9oARxCFfnAhddXW/DDv6AiEvDaNhhxsfc7wcOnJc Vh7e4rHXcREneMYONUXvx/lYlZFZio0= ARC-Authentication-Results: i=1; imf12.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=SGj7NgT5; dmarc=pass (policy=none) header.from=lwn.net; spf=pass (imf12.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1731096734; a=rsa-sha256; cv=none; b=ybUd44U/GRLlLKOgoto8szL6aP29OJXER+WSYsA4KR6qPxTKEkmVAe/Y/ayoaaE+zi4cBz z5VbIyEk/zRnKqJ+zgQiSt1Chnlcw42ZlqINWV7FEUd6tnbJ8uTsLN82aRanRXjxjZ/2ET Y5ccwadSFUMWwoZyO905vN3hGNM0tlo= DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 5DC3F42C17 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1731096808; bh=SdL8Q8EQQQJJ8xM8160z/ZDZmIkZmULZbC6xpHvhB2g=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=SGj7NgT5pCq9qMZMXNJKG2UgQ/lP9zZE4YbKvUXqgPrUznXNr6/HcfYciET1a180c 4CQEBIeK0nih1ZtSbGeYgYPx/hYb6yPDREd8OyH5nekdazyQhbd0FntwwvCDHijkAQ AiRe9/OS3QLp/eLystk6jgqxf76GfzScZi/3peY4z6raTJ/W27faMyuX0o0Qblo8bn kulpZfzb4/cWAHAGIm0JQYi2CeCfIdC74UulY5RY8yhiiQV9VTsz3uVWHk/HuMjiz7 crwtMtMpBsv4BAZjxgb2arxdBkDSSgw/l0R41+5urv/u4+CiW8A60jFzuPQy7tWs5l BT3AAiFW7pn8Q== Received: from localhost (unknown [IPv6:2601:280:5e00:625::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 5DC3F42C17; Fri, 8 Nov 2024 20:13:28 +0000 (UTC) From: Jonathan Corbet To: Leon Romanovsky 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 , =?utf-8?B?SsOpcsO0bWU=?= 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 In-Reply-To: <20241108200355.GC189042@unreal> References: <881ef0bcf9aa971e995fbdd00776c5140a7b5b3d.1730298502.git.leon@kernel.org> <87ttchwmde.fsf@trenco.lwn.net> <20241108200355.GC189042@unreal> Date: Fri, 08 Nov 2024 13:13:27 -0700 Message-ID: <87h68hwkk8.fsf@trenco.lwn.net> MIME-Version: 1.0 Content-Type: text/plain X-Rspam-User: X-Rspamd-Server: rspam03 X-Rspamd-Queue-Id: AD46540008 X-Stat-Signature: m1ob14qqp4gn1jbsmdmhex7sjnrnmb7k X-HE-Tag: 1731096802-609003 X-HE-Meta: U2FsdGVkX18bMOh60DTbSiA8aqXUHRYHvr60LmbdEKrLp0d0HZNaW2aPYwX/KaJ64nNdxEVk9pErg50TABRdKVnJgohS7t8HSjULPpIOkq+5TU2CHcURPDOPMwHnGTN801DQ6GXpT6PQBgB4bk/cLjtjh3X1RMCmwyUdZx2kQnP1gt/HpbsTCxvbblc/BKyGeKng9YdWMndukASQdL2JoTfJyYUSnABL1FVpZcNbhSBEG+otJG63J9zbQ4WWaKy6UwU5pUUN82hs9I+iHfLrD8QQfPfAgxqCA3fLg2b5A1kI6SZOXVGdKijKwkHdoHGIHrM/RwCM5hfErypHZvSohaTG6ZVLmXyQGmCCFT7Wc9u3vYu+K5HE0GZ2gVlJKpAnFX9LjAo8xs/ylrjj42ql9hHnRIMI/LAIxF5jRJUlgYZMiNpnBSSh9G7SnUR8ZRZmikLfcaRD8xeSg+7C1xQOwnBSJ/ccB/NrfgiPmMXucd3TvD6rWZqf44tgF+dcR8apMgoWs/eOeOvWyV2GjnZjL1movUvq/piH8cxmWdBhA8Hws14uifgotOdvS3Gdf+C6vpiq5daggIhH1/jDhIRgGAQpIqxAJKIJbFGjlQ6JjiFPaS8P/0xOMl0SdgQJonCIgKBXmLq2ikejq/Bdh16+xNIWKuLlFTfSz4K7eVGesGKyO8nyt5WyUb2H1H/xeSpwRBtqr3I6fIJ5V0r0E6HSIkgUK+XQjSCbeMx/MeGnC9cebn0jOSebGHCsWJQhpVkc8/ud18x4wyYaPBqlTblLx3Qvj3qCVbfCR0AbeqKvAO9aqhNAwdmdHUTYRb8Pa1mA0hgqIC/mkBJ38Op0aKiKV4A+CpRFKjFvFpkA9m2cPlr18tLUghhtAdMTkHje8K4+pQ/waiglV5gd6Ewcfwm3/MrIXHdm3QoMlL+SFarxT5zcfKv5Vl//bgSxadCMocxBRbPfyPOhne+pLDfBGW+ 1yU4FFcQ IAmUodHRyyTbhxfC4MBmmC/g1nNDMpDBBSCCzWitD1EAgVdWFmwvZQ1KGSXEsymJFuvQpw5SA0NBLwr98nAqEmQzkvGC4SGEmWjQ2SYO2MRQO9KQc7ABP8K68Xnijpsz3pTHjTOFatO60RBP6ps0k78PeWF0OAAhygPeB0pd8OE0IfhSFkpeg60FtNKP+znrTgxE7uUwngpZ2d9J3yRN2IEWM4iaAOIwd+ohc44Q1vKjn3s1MWayFs0gNEP3xEGJTUhIMPcicQAWNSPI= 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: 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, jon