{"id":2197681,"url":"http://patchwork.ozlabs.org/api/1.0/patches/2197681/?format=json","project":{"id":46,"url":"http://patchwork.ozlabs.org/api/1.0/projects/46/?format=json","name":"Intel Wired Ethernet development","link_name":"intel-wired-lan","list_id":"intel-wired-lan.osuosl.org","list_email":"intel-wired-lan@osuosl.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"","date":"2026-02-18T10:13:02","name":"[32/38] docs: kdoc_files: document KernelFiles() ABI","commit_ref":null,"pull_url":null,"state":"handled-elsewhere","archived":false,"hash":"9d6747d82f605fbb703792c76c6a58c86f3f6bd2","submitter":{"id":78235,"url":"http://patchwork.ozlabs.org/api/1.0/people/78235/?format=json","name":"Mauro Carvalho Chehab","email":"mchehab+huawei@kernel.org"},"delegate":null,"mbox":"http://patchwork.ozlabs.org/project/intel-wired-lan/patch/ca064642fd70b1dd2fa2c72a119a3a579ef0a3c2.1771408406.git.mchehab+huawei@kernel.org/mbox/","series":[{"id":492532,"url":"http://patchwork.ozlabs.org/api/1.0/series/492532/?format=json","date":"2026-02-18T10:12:30","name":"docs: several improvements to kernel-doc","version":1,"mbox":"http://patchwork.ozlabs.org/series/492532/mbox/"}],"check":"pending","checks":"http://patchwork.ozlabs.org/api/patches/2197681/checks/","tags":{},"headers":{"Return-Path":"","X-Original-To":["incoming@patchwork.ozlabs.org","intel-wired-lan@lists.osuosl.org"],"Delivered-To":["patchwork-incoming@legolas.ozlabs.org","intel-wired-lan@lists.osuosl.org"],"Authentication-Results":["legolas.ozlabs.org;\n\tdkim=pass (2048-bit key;\n unprotected) header.d=osuosl.org header.i=@osuosl.org header.a=rsa-sha256\n header.s=default header.b=4lwJS5/8;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=osuosl.org\n (client-ip=2605:bc80:3010::138; helo=smtp1.osuosl.org;\n envelope-from=intel-wired-lan-bounces@osuosl.org;\n receiver=patchwork.ozlabs.org)"],"Received":["from smtp1.osuosl.org (smtp1.osuosl.org [IPv6:2605:bc80:3010::138])\n\t(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n\t key-exchange x25519 server-signature ECDSA (secp384r1) server-digest SHA384)\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4fGC5p3qDbz1xpl\n\tfor ; Wed, 18 Feb 2026 21:13:50 +1100 (AEDT)","from localhost (localhost [127.0.0.1])\n\tby smtp1.osuosl.org (Postfix) with ESMTP id B1FC2810BE;\n\tWed, 18 Feb 2026 10:13:45 +0000 (UTC)","from smtp1.osuosl.org ([127.0.0.1])\n by localhost (smtp1.osuosl.org [127.0.0.1]) (amavis, port 10024) with ESMTP\n id 3dbFvETJOvRo; Wed, 18 Feb 2026 10:13:44 +0000 (UTC)","from lists1.osuosl.org (lists1.osuosl.org [140.211.166.142])\n\tby smtp1.osuosl.org (Postfix) with ESMTP id E949A810B0;\n\tWed, 18 Feb 2026 10:13:43 +0000 (UTC)","from smtp1.osuosl.org (smtp1.osuosl.org [IPv6:2605:bc80:3010::138])\n by lists1.osuosl.org (Postfix) with ESMTP id 5D165206\n for ; Wed, 18 Feb 2026 10:13:33 +0000 (UTC)","from localhost (localhost [127.0.0.1])\n by smtp1.osuosl.org (Postfix) with ESMTP id 3FA1E810B6\n for ; Wed, 18 Feb 2026 10:13:33 +0000 (UTC)","from smtp1.osuosl.org ([127.0.0.1])\n by localhost (smtp1.osuosl.org [127.0.0.1]) (amavis, port 10024) with ESMTP\n id VS8mePKkIRm2 for ;\n Wed, 18 Feb 2026 10:13:32 +0000 (UTC)","from tor.source.kernel.org (tor.source.kernel.org [172.105.4.254])\n by smtp1.osuosl.org (Postfix) with ESMTPS id 4CD0D810A5\n for ; Wed, 18 Feb 2026 10:13:32 +0000 (UTC)","from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58])\n by tor.source.kernel.org (Postfix) with ESMTP id 712BC61862;\n Wed, 18 Feb 2026 10:13:31 +0000 (UTC)","by smtp.kernel.org (Postfix) with ESMTPSA id 26B82C19421;\n Wed, 18 Feb 2026 10:13:31 +0000 (UTC)","from mchehab by mail.kernel.org with local (Exim 4.99.1)\n (envelope-from )\n id 1vseYj-00000000Lxe-1kJB; Wed, 18 Feb 2026 11:13:29 +0100"],"X-Virus-Scanned":["amavis at osuosl.org","amavis at osuosl.org"],"X-Comment":"SPF check N/A for local connections - client-ip=140.211.166.142;\n helo=lists1.osuosl.org; envelope-from=intel-wired-lan-bounces@osuosl.org;\n receiver= ","DKIM-Filter":["OpenDKIM Filter v2.11.0 smtp1.osuosl.org E949A810B0","OpenDKIM Filter v2.11.0 smtp1.osuosl.org 4CD0D810A5"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=osuosl.org;\n\ts=default; t=1771409624;\n\tbh=ZFarqj/R/r3ArEfpTLMMZ2sYAwIm9hgPCWPCcnBmnQU=;\n\th=From:To:Cc:Date:In-Reply-To:References:Subject:List-Id:\n\t List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe:\n\t From;\n\tb=4lwJS5/88P5LN9jnpz/L8/c1sQqZqd7rFtu9rnL9IYiXONBs/tioFLR2hwmaeEhNA\n\t R/FQ0zt72n2wWh74OUTxxdjFvgr1leDRyfuuGVtY1j2s94iXombEGf/J6fJFLUYtzD\n\t r59+9XUt6PTuxSi01lrNb4Q3qPnRDwkk+Tz1RanZngEikkzBpJtQEwzPBcptVN/B+m\n\t AIdJ/eYMYOfrV7fqw84HtCrmUriWOJGuwUK/D285X6nHFV95LzP+BWAQNsXHc6gpvX\n\t 9iynB+WAoc19OFdyOtvUk/pyaXE3eMzF630jOLRQdWFplIXHg+fZyaB+w8AosnFhVO\n\t SbbSZJV23Kxvw==","Received-SPF":"Pass (mailfrom) identity=mailfrom; client-ip=172.105.4.254;\n helo=tor.source.kernel.org; envelope-from=mchehab+huawei@kernel.org;\n receiver=","DMARC-Filter":"OpenDMARC Filter v1.4.2 smtp1.osuosl.org 4CD0D810A5","From":"Mauro Carvalho Chehab ","To":"Jonathan Corbet ,\n Linux Doc Mailing List ","Cc":"Mauro Carvalho Chehab ,\n intel-wired-lan@lists.osuosl.org, linux-hardening@vger.kernel.org,\n linux-kernel@vger.kernel.org, netdev@vger.kernel.org,\n Randy Dunlap ","Date":"Wed, 18 Feb 2026 11:13:02 +0100","Message-ID":"\n ","X-Mailer":"git-send-email 2.52.0","In-Reply-To":"","References":"","MIME-Version":"1.0","Content-Type":"text/plain; charset=\"utf-8\"","Content-Transfer-Encoding":"8bit","X-Mailman-Original-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple;\n d=kernel.org; s=k20201202; t=1771409611;\n bh=93FI6HCbFuKLoTGysvIesP/671jVJYX05qdlxtKR9Kk=;\n h=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n b=D6zqkt/3NUB6EpxHEputgfvaw1vHtc0NsZ65QNN3AAKsJuHWSBcq82NKFzJu8llkR\n S+1bk/UPxulyqkqcMbYtUMX/IIRr09HFtRuwNOA1NPlhPHsSPUiXhECDzbmymTKCPU\n JmPJyAld8CPADXng3h49bxxTnDEx8O6tZ/7uUMOx2P8DlevrZHSEFbuD7SA01tAoZe\n Wy2GDlPrU1hQLkRN135ojO5oHWcW9ckY5i4kcvDUXG5i7xXrBHkp+i3T/cZga64Syq\n yIzxySQ3SnLG+PqvN40MnLlrYGZ278mb8gxtsx2bB1lNqpGUgxCJ6tFZMhIOwetkTl\n /MxbF5cjFyQRg==","X-Mailman-Original-Authentication-Results":["smtp1.osuosl.org;\n dmarc=pass (p=quarantine dis=none)\n header.from=kernel.org","smtp1.osuosl.org;\n dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org\n header.a=rsa-sha256 header.s=k20201202 header.b=D6zqkt/3"],"Subject":"[Intel-wired-lan] [PATCH 32/38] docs: kdoc_files: document\n KernelFiles() ABI","X-BeenThere":"intel-wired-lan@osuosl.org","X-Mailman-Version":"2.1.30","Precedence":"list","List-Id":"Intel Wired Ethernet Linux Kernel Driver Development\n ","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Errors-To":"intel-wired-lan-bounces@osuosl.org","Sender":"\"Intel-wired-lan\" "},"content":"The KernelFiles is the main entry point to run kernel-doc,\nbeing used by both tools/docs/kernel-doc and\nDocumentation/sphinx/kerneldoc.py.\n\nIt is also used on QEMU, which also uses the kernel-doc\nlibraries from tools/lib/python/kdoc.\n\nProperly describe its ABI contract.\n\nSigned-off-by: Mauro Carvalho Chehab \n---\n tools/lib/python/kdoc/kdoc_files.py | 44 ++++++++++++++++++++++++++++-\n 1 file changed, 43 insertions(+), 1 deletion(-)","diff":"diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kdoc_files.py\nindex c35e033cf123..8c2059623949 100644\n--- a/tools/lib/python/kdoc/kdoc_files.py\n+++ b/tools/lib/python/kdoc/kdoc_files.py\n@@ -91,7 +91,49 @@ class KernelFiles():\n \"\"\"\n Parse kernel-doc tags on multiple kernel source files.\n \n- There are two type of parsers defined here:\n+ This is the main entry point to run kernel-doc. This class is initialized\n+ using a series of optional arguments:\n+\n+ ``verbose``\n+ If True, enables kernel-doc verbosity. Default: False.\n+\n+ ``out_style``\n+ Class to be used to format output. If None (default),\n+ only report errors.\n+\n+ ``xforms``\n+ Transforms to be applied to C prototypes and data structs.\n+ If not specified, defaults to xforms = CFunction()\n+\n+ ``werror``\n+ If True, treat warnings as errors, retuning an error code on warnings.\n+\n+ Default: False.\n+\n+ ``wreturn``\n+ If True, warns about the lack of a return markup on functions.\n+\n+ Default: False.\n+ ``wshort_desc``\n+ If True, warns if initial short description is missing.\n+\n+ Default: False.\n+\n+ ``wcontents_before_sections``\n+ If True, warn if there are contents before sections (deprecated).\n+ This option is kept just for backward-compatibility, but it does\n+ nothing, neither here nor at the original Perl script.\n+\n+ Default: False.\n+\n+ ``logger``\n+ Optional logger class instance.\n+\n+ If not specified, defaults to use: ``logging.getLogger(\"kernel-doc\")``\n+\n+ Note:\n+ There are two type of parsers defined here:\n+\n - self.parse_file(): parses both kernel-doc markups and\n ``EXPORT_SYMBOL*`` macros;\n - self.process_export_file(): parses only ``EXPORT_SYMBOL*`` macros.\n","prefixes":["32/38"]}