From nobody Mon Feb 9 19:52:47 2026 Delivered-To: importer@patchew.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 Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1627581580775535.5377380130499; Thu, 29 Jul 2021 10:59:40 -0700 (PDT) Received: from localhost ([::1]:55768 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m9AJn-0006LJ-QP for importer@patchew.org; Thu, 29 Jul 2021 13:59:39 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52446) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGN-0006T5-PY for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:07 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:54367) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGI-0007t4-2k for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:07 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-522-33NwiUv_Ml2fRdJ6cSSfyQ-1; Thu, 29 Jul 2021 13:55:56 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id E51AEC73A1 for ; Thu, 29 Jul 2021 17:55:55 +0000 (UTC) Received: from localhost (unknown [10.22.18.227]) by smtp.corp.redhat.com (Postfix) with ESMTP id AE1CD5D6B1; Thu, 29 Jul 2021 17:55:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627581360; h=from:from: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:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=85ErR7+WiEu/O4u03QCNLmaS5ihB7R0FWBSKyVW3dKQ=; b=PbRJk+XJ9idFTWNeoa5Zx2SKG/3e+DZJL23XQ2nDAzQlpToQ1VuxoLIXA+ex55lCtfHdrY PACXImiVKZRd4nNbku242thRMEOPi2rRhoPo4OHb4zY1h9JfgJ0i/Uf0qqHruxSOMTAZNi UTUsWlK9g+0/B3T4gmqENX/Q2jAVM+0= X-MC-Unique: 33NwiUv_Ml2fRdJ6cSSfyQ-1 From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol` Date: Thu, 29 Jul 2021 13:55:45 -0400 Message-Id: <20210729175554.686474-2-ehabkost@redhat.com> In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com> References: <20210729175554.686474-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable 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; Received-SPF: pass client-ip=170.10.133.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action 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: , Cc: Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1627581581407100003 Content-Type: text/plain; charset="utf-8" Replace leftover of GTK-Doc #name syntax with `name`, and use default-role:: any, so we can add references to other functions, types, and macros. There are 3 cases that required extra care: - #TypeInfo.class_init: kernel-doc doesn't generate c:member:: directives, so references to C struct members are not possible yet. This was replaced with `TypeInfo`.class_init. - #CPUClass.reset and #DeviceClass.realize: cpu.h and qdev docs are not rendered using Sphinx yet, so use ``code`` syntax for those. Signed-off-by: Eduardo Habkost --- docs/devel/qom.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index e5fe3597cd8..9c1be5d7fc2 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -3,6 +3,7 @@ The QEMU Object Model (QOM) =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D =20 .. highlight:: c +.. default-role:: any =20 The QEMU Object Model provides a framework for registering user creatable types and instantiating objects from those types. QOM provides the follow= ing @@ -42,8 +43,8 @@ features: =20 type_init(my_device_register_types) =20 -In the above example, we create a simple type that is described by #TypeIn= fo. -#TypeInfo describes information about the type including what it inherits +In the above example, we create a simple type that is described by `TypeIn= fo`. +`TypeInfo` describes information about the type including what it inherits from, the instance and class size, and constructor/destructor hooks. =20 Alternatively several static types could be registered using helper macro @@ -66,13 +67,13 @@ DEFINE_TYPES() =20 DEFINE_TYPES(device_types_info) =20 -Every type has an #ObjectClass associated with it. #ObjectClass derivativ= es +Every type has an `ObjectClass` associated with it. `ObjectClass` derivat= ives are instantiated dynamically but there is only ever one instance for any -given type. The #ObjectClass typically holds a table of function pointers +given type. The `ObjectClass` typically holds a table of function pointers for the virtual methods implemented by this type. =20 -Using object_new(), a new #Object derivative will be instantiated. You can -cast an #Object to a subclass (or base-class) type using +Using object_new(), a new `Object` derivative will be instantiated. You c= an +cast an `Object` to a subclass (or base-class) type using object_dynamic_cast(). You typically want to define macro wrappers around OBJECT_CHECK() and OBJECT_CLASS_CHECK() to make it easier to convert to a specific type: @@ -111,7 +112,7 @@ The effect of this is that classes automatically inheri= t any virtual function pointers that the parent class has already initialized. All other fields will be zero filled. =20 -Once all of the parent classes have been initialized, #TypeInfo::class_init +Once all of the parent classes have been initialized, `TypeInfo`::class_in= it is called to let the class being instantiated provide default initialize f= or its virtual functions. Here is how the above example might be modified to introduce an overridden virtual function: @@ -135,7 +136,7 @@ to introduce an overridden virtual function: }; =20 Introducing new virtual methods requires a class to define its own -struct and to add a .class_size member to the #TypeInfo. Each method +struct and to add a .class_size member to the `TypeInfo`. Each method will also have a wrapper function to call it easily: =20 .. code-block:: c @@ -188,12 +189,12 @@ strongly-typed first argument. If it does not operate on an object instance, it is dubbed *class method*. =20 -Methods cannot be overloaded. That is, the #ObjectClass and method name +Methods cannot be overloaded. That is, the `ObjectClass` and method name uniquely identity the function to be called; the signature does not vary except for trailing varargs. =20 Methods are always *virtual*. Overriding a method in -#TypeInfo.class_init of a subclass leads to any user of the class obtained +`TypeInfo`.class_init of a subclass leads to any user of the class obtained via OBJECT_GET_CLASS() accessing the overridden function. The original function is not automatically invoked. It is the responsibili= ty of the overriding class to determine whether and when to invoke the method @@ -273,8 +274,8 @@ Alternatively, object_class_by_name() can be used to ob= tain the class and its non-overridden methods for a specific type. This would correspond to ``MyClass::method(...)`` in C++. =20 -The first example of such a QOM method was #CPUClass.reset, -another example is #DeviceClass.realize. +The first example of such a QOM method was ``CPUClass.reset``, +another example is ``DeviceClass.realize``. =20 Standard type declaration and definition macros =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --=20 2.31.1