From nobody Mon Feb 9 00:44:46 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1576673458; cv=none; d=zohomail.com; s=zohoarc; b=XVCSZU8UD/yDHLStErC8iCWqdq+o30nJ7A3kjxAdC3Q9H0HVAHcqOkK/Q7iQhEHktEKixW2exXukD9RIQDDGmL3CdN3oJ/P2Qjj7PxyhOGle6hDGcKvWIWQ0Mg/hX3zPOgmRzVePC9uJCDNrWJLpJHxVT8cGiLXdjuuYoU9YQ4c= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1576673458; h=Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:Message-ID:References:Sender:Subject:To; bh=KB33/P7pdd5zyToITAll1MNS1ualBhVbh7OSCHIhH1g=; b=XTrSL//Q2Te46Ob7/cG1owN0bbmDJr8JzdWTZM9pxU+v4nkhYboc+VZTDXdOe6LZnjHYokf1jvMpW2WWnJzd2kHT1zDDE5rT32ZTT+AM0e8h8xyJ8XtoxQsHYSNVaP97OdHBZzcWu6D/AZYWnxASoU+p42NPGUASILkGJl2uf6k= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1576673458942239.2698003374975; Wed, 18 Dec 2019 04:50:58 -0800 (PST) Received: from localhost ([::1]:53748 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ihYn3-0004Lh-Hy for importer@patchew.org; Wed, 18 Dec 2019 07:50:57 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:55443) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ihY3n-0007EU-2c for qemu-devel@nongnu.org; Wed, 18 Dec 2019 07:04:13 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ihY3l-00033o-Nd for qemu-devel@nongnu.org; Wed, 18 Dec 2019 07:04:10 -0500 Received: from mail-wm1-x343.google.com ([2a00:1450:4864:20::343]:52347) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ihY3l-0002zW-Em for qemu-devel@nongnu.org; Wed, 18 Dec 2019 07:04:09 -0500 Received: by mail-wm1-x343.google.com with SMTP id p9so1563865wmc.2 for ; Wed, 18 Dec 2019 04:04:09 -0800 (PST) Received: from 640k.lan ([93.56.166.5]) by smtp.gmail.com with ESMTPSA id n67sm2236838wmf.46.2019.12.18.04.04.07 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 18 Dec 2019 04:04:07 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:subject:date:message-id:in-reply-to:references; bh=KB33/P7pdd5zyToITAll1MNS1ualBhVbh7OSCHIhH1g=; b=a5KkxY0GKUs696wveW2SDwo8j8SUpugFuqA5PWnurYSrKg1fPmFGrSXTNx9MXRhJNi 92ML/clLkiG6j66Xb1HsdRK0Svxl3wbgdjfGZfj6S/3ESt+6mmOfC7QvdJZ0pMFdGjL1 SrHcjuh7GaUbVqvus/XZWDun1WaXygFLXmQn1BdOy6sHBrJal1Go6ewACO8HosFGnTOR 2m/duyWLQdER82AZigpu0XVNQ7xBV+z2s2eGtnAak0Jh3LNeY6SSODxwTjEX9sTdaDVJ nKKzFTXcVNkD4idsbPfNORE/xwQQ71poGenLoSw//qxYYgaNF3Ps9GII/2U4xjrDPmt5 ECyQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:subject:date:message-id :in-reply-to:references; bh=KB33/P7pdd5zyToITAll1MNS1ualBhVbh7OSCHIhH1g=; b=gI18tC95cNrnPLmCfMYV0QmNLlRN9Ox9GfKwax15B7EVinN61sBdmbU4MixyA5JH8i HgJeF9GBKecqbiIYZ4GpZbSPR17MV9TiAAW6XKPM36Pk6baZ9J0sUCbWqBXvKQqZTRap 5BicvynWmmqNLRkMdRtSa5nar0xFMKqnqqQrhI8GzShqPkK+4PEqLSFrGShXtKC2SMC2 rlvzXrav5Z/XhcKDMThRa+lwi4lRgU3+Svkj0K7G3WtLkdGaA4DoTiGH+/WaUZmLNv2n YH/EcLX/EDw3w8wZnKwzG07JxAH/Ufpm7LidfTdnNjmz/nuVt5nPxgBvtO3Lz03svE/6 KZrA== X-Gm-Message-State: APjAAAUvSLrTIhda6rBm8LN25tZGV3/+7vK5EBEzknuzUD2clJ1n9veU z3IWCj0S2F//dJ0ei4aTdjkeOa/F X-Google-Smtp-Source: APXvYqzVdydMVMI3qwU86/NfcSMDBIwbXJ2bSKYBFhntj02NZmJFTnLxKeRxdvbQcPm0C5JRB/UtFw== X-Received: by 2002:a1c:7d92:: with SMTP id y140mr2641764wmc.145.1576670648148; Wed, 18 Dec 2019 04:04:08 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PULL 65/87] docs: tweak kernel-doc for QEMU coding standards Date: Wed, 18 Dec 2019 13:02:31 +0100 Message-Id: <1576670573-48048-66-git-send-email-pbonzini@redhat.com> X-Mailer: git-send-email 1.8.3.1 In-Reply-To: <1576670573-48048-1-git-send-email-pbonzini@redhat.com> References: <1576670573-48048-1-git-send-email-pbonzini@redhat.com> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::343 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Surprisingly, QEMU does have a pretty consistent doc comment style and it is not very different from the Linux kernel's. Of the documentation "sigils", only "#" separates the QEMU doc comment style from Linux's, and it has 200+ instances vs. 6 for the kernel's '&struct foo' (all in accel/tcg/translate-all.c), so it's clear that the two standards are different in this respect. In addition, our structs are typedefed and recognized by CamelCase names. Adjust kernel-doc's parser for these two aspects of the QEMU coding standards. The patch has been valid, with hardly any change, for over two years, so it should not be an issue to keep kernel-doc in sync with the Linux copy. Signed-off-by: Paolo Bonzini --- scripts/kernel-doc | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 81dc917..af470eb 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -215,12 +215,12 @@ my $type_func =3D '(\w+)\(\)'; my $type_param =3D '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; my $type_fp_param =3D '\@(\w+)\(\)'; # Special RST handling for func ptr = params my $type_env =3D '(\$\w+)'; -my $type_enum =3D '\&(enum\s*([_\w]+))'; -my $type_struct =3D '\&(struct\s*([_\w]+))'; -my $type_typedef =3D '\&(typedef\s*([_\w]+))'; -my $type_union =3D '\&(union\s*([_\w]+))'; -my $type_member =3D '\&([_\w]+)(\.|->)([_\w]+)'; -my $type_fallback =3D '\&([_\w]+)'; +my $type_enum =3D '#(enum\s*([_\w]+))'; +my $type_struct =3D '#(struct\s*([_\w]+))'; +my $type_typedef =3D '#(([A-Z][_\w]*))'; +my $type_union =3D '#(union\s*([_\w]+))'; +my $type_member =3D '#([_\w]+)(\.|->)([_\w]+)'; +my $type_fallback =3D '(?!)'; # this never matches my $type_member_func =3D $type_member . '\(\)'; =20 # Output conversion substitutions. @@ -1050,6 +1050,14 @@ sub output_blockhead { sub dump_declaration($$) { no strict 'refs'; my ($prototype, $file) =3D @_; + if ($decl_type eq 'type name') { + if ($prototype =3D~ /^(enum|struct|union)\s+/) { + $decl_type =3D $1; + } else { + return; + } + } + my $func =3D "dump_" . $decl_type; &$func(@_); } @@ -1878,7 +1886,7 @@ sub process_name($$) { } elsif (/$doc_decl/o) { $identifier =3D $1; - if (/\s*([\w\s]+?)(\(\))?\s*-/) { + if (/\s*([\w\s]+?)(\s*-|:)/) { $identifier =3D $1; } =20 @@ -1888,7 +1896,7 @@ sub process_name($$) { $contents =3D ""; $section =3D $section_default; $new_start_line =3D $. + 1; - if (/-(.*)/) { + if (/[-:](.*)/) { # strip leading/trailing/multiple spaces $descr=3D $1; $descr =3D~ s/^\s*//; @@ -1906,7 +1914,9 @@ sub process_name($$) { ++$warnings; } =20 - if ($identifier =3D~ m/^struct\b/) { + if ($identifier =3D~ m/^[A-Z]/) { + $decl_type =3D 'type name'; + } elsif ($identifier =3D~ m/^struct\b/) { $decl_type =3D 'struct'; } elsif ($identifier =3D~ m/^union\b/) { $decl_type =3D 'union'; --=20 1.8.3.1