Cover Letter Detail
Show a cover letter.
GET /api/1.0/covers/2197647/?format=api
{ "id": 2197647, "url": "http://patchwork.ozlabs.org/api/1.0/covers/2197647/?format=api", "project": { "id": 46, "url": "http://patchwork.ozlabs.org/api/1.0/projects/46/?format=api", "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": "<cover.1771408406.git.mchehab+huawei@kernel.org>", "date": "2026-02-18T10:12:30", "name": "[00/38] docs: several improvements to kernel-doc", "submitter": { "id": 78235, "url": "http://patchwork.ozlabs.org/api/1.0/people/78235/?format=api", "name": "Mauro Carvalho Chehab", "email": "mchehab+huawei@kernel.org" }, "series": [ { "id": 492532, "url": "http://patchwork.ozlabs.org/api/1.0/series/492532/?format=api", "date": "2026-02-18T10:12:30", "name": "docs: several improvements to kernel-doc", "version": 1, "mbox": "http://patchwork.ozlabs.org/series/492532/mbox/" } ], "headers": { "Return-Path": "<intel-wired-lan-bounces@osuosl.org>", "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=xUfpb1QQ;\n\tdkim-atps=neutral", "legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=osuosl.org\n (client-ip=2605:bc80:3010::136; helo=smtp3.osuosl.org;\n envelope-from=intel-wired-lan-bounces@osuosl.org;\n receiver=patchwork.ozlabs.org)" ], "Received": [ "from smtp3.osuosl.org (smtp3.osuosl.org [IPv6:2605:bc80:3010::136])\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 4fGC5K0G9Xz1xpl\n\tfor <incoming@patchwork.ozlabs.org>; Wed, 18 Feb 2026 21:13:24 +1100 (AEDT)", "from localhost (localhost [127.0.0.1])\n\tby smtp3.osuosl.org (Postfix) with ESMTP id 75DD7605E6;\n\tWed, 18 Feb 2026 10:13:23 +0000 (UTC)", "from smtp3.osuosl.org ([127.0.0.1])\n by localhost (smtp3.osuosl.org [127.0.0.1]) (amavis, port 10024) with ESMTP\n id ho7zFfRNfa8T; Wed, 18 Feb 2026 10:13:22 +0000 (UTC)", "from lists1.osuosl.org (lists1.osuosl.org [140.211.166.142])\n\tby smtp3.osuosl.org (Postfix) with ESMTP id 6CFC9605DC;\n\tWed, 18 Feb 2026 10:13:22 +0000 (UTC)", "from smtp2.osuosl.org (smtp2.osuosl.org [IPv6:2605:bc80:3010::133])\n by lists1.osuosl.org (Postfix) with ESMTP id 3DBFB438\n for <intel-wired-lan@lists.osuosl.org>; Wed, 18 Feb 2026 10:13:20 +0000 (UTC)", "from localhost (localhost [127.0.0.1])\n by smtp2.osuosl.org (Postfix) with ESMTP id 21FCB4009A\n for <intel-wired-lan@lists.osuosl.org>; Wed, 18 Feb 2026 10:13:20 +0000 (UTC)", "from smtp2.osuosl.org ([127.0.0.1])\n by localhost (smtp2.osuosl.org [127.0.0.1]) (amavis, port 10024) with ESMTP\n id yVI5om3x7Ur7 for <intel-wired-lan@lists.osuosl.org>;\n Wed, 18 Feb 2026 10:13:19 +0000 (UTC)", "from sea.source.kernel.org (sea.source.kernel.org\n [IPv6:2600:3c0a:e001:78e:0:1991:8:25])\n by smtp2.osuosl.org (Postfix) with ESMTPS id DEFAA40078\n for <intel-wired-lan@lists.osuosl.org>; Wed, 18 Feb 2026 10:13:18 +0000 (UTC)", "from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58])\n by sea.source.kernel.org (Postfix) with ESMTP id 16AFA416DB;\n Wed, 18 Feb 2026 10:13:18 +0000 (UTC)", "by smtp.kernel.org (Postfix) with ESMTPSA id E0DC7C19423;\n Wed, 18 Feb 2026 10:13:17 +0000 (UTC)", "from mchehab by mail.kernel.org with local (Exim 4.99.1)\n (envelope-from <mchehab+huawei@kernel.org>)\n id 1vseYV-00000000LJW-3Io3; Wed, 18 Feb 2026 11:13:15 +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=<UNKNOWN> ", "DKIM-Filter": [ "OpenDKIM Filter v2.11.0 smtp3.osuosl.org 6CFC9605DC", "OpenDKIM Filter v2.11.0 smtp2.osuosl.org DEFAA40078" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=osuosl.org;\n\ts=default; t=1771409602;\n\tbh=INQWUBoHdyd40KVmSGoHZIr5TihUkQlSREp3ffp220M=;\n\th=From:To:Cc:Date:Subject:List-Id:List-Unsubscribe:List-Archive:\n\t List-Post:List-Help:List-Subscribe:From;\n\tb=xUfpb1QQwD7kUw1rJM0Ol57SLTFqz0CbpOvyMWuQkl+MUoeJu37kBkWC/wkg8MASU\n\t CyiZGwV6QG9e87+JB2br/Xj0zo5WbSXSiyzgzNsiuWOBmWFHFGiuw88YqC8Il7VVmJ\n\t QymyF4RtY7pEElAUhZ2ukHmp4q01lzIZSHxn5gTsvBcIRV3l4cxQLtZQwOWdQKxo/k\n\t CSIy9p+PlBx8/oeoCFwCDc1XwgS54OsOx7rYLBUNvpZQQsnsU14BdRPiXX0d6q/MTa\n\t ENy/qfTE+YyR71HiZBNq+zS/jHmXSG1Bg/rQBRJjAg22BNz/JfrgMJI/Gq/qwu04bE\n\t BvNP0SceJE+3A==", "Received-SPF": "Pass (mailfrom) identity=mailfrom;\n client-ip=2600:3c0a:e001:78e:0:1991:8:25; helo=sea.source.kernel.org;\n envelope-from=mchehab+huawei@kernel.org; receiver=<UNKNOWN>", "DMARC-Filter": "OpenDMARC Filter v1.4.2 smtp2.osuosl.org DEFAA40078", "From": "Mauro Carvalho Chehab <mchehab+huawei@kernel.org>", "To": "Alexander Lobakin <aleksander.lobakin@intel.com>,\n Jonathan Corbet <corbet@lwn.net>, Kees Cook <kees@kernel.org>,\n Mauro Carvalho Chehab <mchehab@kernel.org>", "Cc": "Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,\n intel-wired-lan@lists.osuosl.org, linux-doc@vger.kernel.org,\n linux-hardening@vger.kernel.org, linux-kernel@vger.kernel.org,\n netdev@vger.kernel.org, \"Gustavo A. R. Silva\" <gustavoars@kernel.org>,\n Aleksandr Loktionov <aleksandr.loktionov@intel.com>,\n Randy Dunlap <rdunlap@infradead.org>,\n Shuah Khan <skhan@linuxfoundation.org>", "Date": "Wed, 18 Feb 2026 11:12:30 +0100", "Message-ID": "<cover.1771408406.git.mchehab+huawei@kernel.org>", "X-Mailer": "git-send-email 2.52.0", "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=1771409597;\n bh=hQYWDaTIE85+WOC6CQ6nA1VAXpHb84+B8MfLik8/hPM=;\n h=From:To:Cc:Subject:Date:From;\n b=d02Pp71Fm4vMO7efubkTyWYQJv6OqhWDcfH7yDy5f3q/bpJvvParwNqbJnu6fD63z\n XXD9RwmeBKw6NyttSW1D1sdSfxwcLeYO9ZRCjhsK+c1MlvUhojI+3xhmDh3LLn4byr\n uEf4t/XgAsbWQXgKwc7Mgotuz0tz4qk8hsLsqkSQrbrYysWJ8It1Dk9g6/MsQN6phC\n dBcI8WfcmzOPKKhS8J77QRwNhbjQM8FjmA4wmqNAcZBmWhyXMbmQ8IonJtah5jYby7\n Cl+G8tW4Bsd+rxAUUmIfQws2Qy+3DyAaWEEuyfbMYdoZ6DDl1axycFfQd8/asJm6Eo\n jBuuXgC8wniDA==", "X-Mailman-Original-Authentication-Results": [ "smtp2.osuosl.org;\n dmarc=pass (p=quarantine dis=none)\n header.from=kernel.org", "smtp2.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=d02Pp71F" ], "Subject": "[Intel-wired-lan] [PATCH 00/38] docs: several improvements to\n kernel-doc", "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 <intel-wired-lan.osuosl.org>", "List-Unsubscribe": "<https://lists.osuosl.org/mailman/options/intel-wired-lan>,\n <mailto:intel-wired-lan-request@osuosl.org?subject=unsubscribe>", "List-Archive": "<http://lists.osuosl.org/pipermail/intel-wired-lan/>", "List-Post": "<mailto:intel-wired-lan@osuosl.org>", "List-Help": "<mailto:intel-wired-lan-request@osuosl.org?subject=help>", "List-Subscribe": "<https://lists.osuosl.org/mailman/listinfo/intel-wired-lan>,\n <mailto:intel-wired-lan-request@osuosl.org?subject=subscribe>", "Errors-To": "intel-wired-lan-bounces@osuosl.org", "Sender": "\"Intel-wired-lan\" <intel-wired-lan-bounces@osuosl.org>" }, "content": "Hi Jon,\n\nThis series contain several improvements for kernel-doc.\n\nMost of the patches came from v4 of this series:\n\thttps://lore.kernel.org/linux-doc/cover.1769867953.git.mchehab+huawei@kernel.org/\n\nBut I dropped from this series the unit tests part. I'll\nbe sumitting it on a separate series.\n\nThe rationale is that, when I converted kernel-doc from Perl,\nthe goal were to produce a bug-compatible version.\n\nAs anyone that worked before with kernel-doc are aware, using regex to\nhandle C input is not great. Instead, we need something closer to how\nC statements and declarations are handled.\n\nYet, to avoid breaking docs, I avoided touching the regex-based algorithms\ninside it with one exception: struct_group logic was using very complex\nregexes that are incompatible with Python internal \"re\" module.\n\nSo, I came up with a different approach: NestedMatch. The logic inside\nit is meant to properly handle brackets, square brackets and parenthesis,\nwhich is closer to what C lexical parser does. On that time, I added\na TODO about the need to extend that.\n\nThe first part of this series do exactly that: it extends it to parse\ncomma-separated arguments, respecting brackets and parenthesis.\n\nIt then adds an \"alias\" to it at class CFunction. With that, specifying\nfunctions/macros to be handled becomes much easier.\n\nWith such infra in place, it moves the transform functions to a separate\nfile, making it hopefully easier to maintain. As a side effect, it also\nmakes easier for other projects to use kernel-doc (I tested it on QEMU).\n\nThen, it adds support for newer kref annotations.\n\nThe remaining patches on this series improve the man page output, making\nthem more compatible with other man pages.\n\n-\n\nI wrote several unit tests to check kernel-doc behavior. I intend to\nsubmit them on the top of this series later on.\n\nRegards,\nMauro\n\nMauro Carvalho Chehab (36):\n docs: kdoc_re: add support for groups()\n docs: kdoc_re: don't go past the end of a line\n docs: kdoc_parser: move var transformers to the beginning\n docs: kdoc_parser: don't mangle with function defines\n docs: kdoc_parser: add functions support for NestedMatch\n docs: kdoc_parser: use NestedMatch to handle __attribute__ on\n functions\n docs: kdoc_parser: fix variable regexes to work with size_t\n docs: kdoc_parser: fix the default_value logic for variables\n docs: kdoc_parser: add some debug for variable parsing\n docs: kdoc_parser: don't exclude defaults from prototype\n docs: kdoc_parser: fix parser to support multi-word types\n docs: kdoc_parser: add support for LIST_HEAD\n docs: kdoc_re: properly handle strings and escape chars on it\n docs: kdoc_re: better show KernRe() at documentation\n docs: kdoc_re: don't recompile NestedMatch regex every time\n docs: kdoc_re: Change NestedMath args replacement to \\0\n docs: kdoc_re: make NestedMatch use KernRe\n docs: kdoc_re: add support on NestedMatch for argument replacement\n docs: kdoc_parser: better handle struct_group macros\n docs: kdoc_re: fix a parse bug on struct page_pool_params\n docs: kdoc_re: add a helper class to declare C function matches\n docs: kdoc_parser: use the new CFunction class\n docs: kdoc_parser: minimize differences with struct_group_tagged\n docs: kdoc_parser: move transform lists to a separate file\n docs: kdoc_re: don't remove the trailing \";\" with NestedMatch\n docs: kdoc_re: prevent adding whitespaces on sub replacements\n docs: xforms_lists.py: use CFuntion to handle all function macros\n docs: kdoc_files: allows the caller to use a different xforms class\n docs: kdoc_re: Fix NestedMatch.sub() which causes PDF builds to break\n docs: kdoc_files: document KernelFiles() ABI\n docs: kdoc_output: add optional args to ManOutput class\n docs: sphinx-build-wrapper: better handle troff .TH markups\n docs: kdoc_output: use a more standard order for .TH on man pages\n docs: sphinx-build-wrapper: don't allow \"/\" on file names\n docs: kdoc_output: describe the class init parameters\n docs: kdoc_output: pick a better default for modulename\n\nRandy Dunlap (2):\n docs: kdoc_parser: ignore context analysis and lock attributes\n docs: kdoc_parser: handle struct member macro\n VIRTIO_DECLARE_FEATURES(name)\n\n Documentation/tools/kdoc_parser.rst | 8 +\n tools/docs/kernel-doc | 1 -\n tools/docs/sphinx-build-wrapper | 9 +-\n tools/lib/python/kdoc/kdoc_files.py | 54 +++++-\n tools/lib/python/kdoc/kdoc_output.py | 73 ++++++--\n tools/lib/python/kdoc/kdoc_parser.py | 183 ++++---------------\n tools/lib/python/kdoc/kdoc_re.py | 242 ++++++++++++++++++++------\n tools/lib/python/kdoc/xforms_lists.py | 109 ++++++++++++\n 8 files changed, 451 insertions(+), 228 deletions(-)\n create mode 100644 tools/lib/python/kdoc/xforms_lists.py" }