From nobody Mon Feb 9 17:23:38 2026 Delivered-To: importer@patchew.org Received-SPF: none (zohomail.com: 8.43.85.245 is neither permitted nor denied by domain of lists.libvirt.org) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; spf=none (zohomail.com: 8.43.85.245 is neither permitted nor denied by domain of lists.libvirt.org) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 170842236150241.9542382255994; Tue, 20 Feb 2024 01:46:01 -0800 (PST) Received: by lists.libvirt.org (Postfix, from userid 996) id 6D4D51E53; Tue, 20 Feb 2024 04:46:00 -0500 (EST) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id 0159A1DC5; Tue, 20 Feb 2024 04:41:59 -0500 (EST) Received: by lists.libvirt.org (Postfix, from userid 996) id 5D9FC18F1; Tue, 20 Feb 2024 04:41:41 -0500 (EST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id B7BCF176C for ; Tue, 20 Feb 2024 04:41:40 -0500 (EST) Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-487-FN1CKnibMkqBrhzGaVjj_w-1; Tue, 20 Feb 2024 04:41:38 -0500 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 8054B38143B0 for ; Tue, 20 Feb 2024 09:41:38 +0000 (UTC) Received: from harajuku.usersys.redhat.com.homenet.telecomitalia.it (unknown [10.45.224.52]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 186631074A for ; Tue, 20 Feb 2024 09:41:37 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_NONE, T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.4 X-MC-Unique: FN1CKnibMkqBrhzGaVjj_w-1 From: Andrea Bolognani To: devel@lists.libvirt.org Subject: [PATCH 1/9] docs: Format lists of files better Date: Tue, 20 Feb 2024 10:41:27 +0100 Message-ID: <20240220094135.359112-2-abologna@redhat.com> In-Reply-To: <20240220094135.359112-1-abologna@redhat.com> References: <20240220094135.359112-1-abologna@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.5 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Message-ID-Hash: RTPXUNX5TECTJA6Q7JAYAZP6T6URHRGB X-Message-ID-Hash: RTPXUNX5TECTJA6Q7JAYAZP6T6URHRGB X-MailFrom: abologna@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: Content-Type: text/plain; charset="utf-8"; x-default="true" Content-Transfer-Encoding: quoted-printable X-ZM-MESSAGEID: 1708422396235100001 Signed-off-by: Andrea Bolognani --- docs/api_extension.rst | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/api_extension.rst b/docs/api_extension.rst index 152e64487e..a42c82daca 100644 --- a/docs/api_extension.rst +++ b/docs/api_extension.rst @@ -73,14 +73,16 @@ The first task is to define the public API. If the new = API involves an XML extension, you have to enhance the RelaxNG schema and document the new elements or attributes: =20 -``src/conf/schemas/domaincommon.rng docs/formatdomain.rst`` +* ``src/conf/schemas/domaincommon.rng`` +* ``docs/formatdomain.rst`` =20 If the API extension involves a new function, you have to add a declaration in the public header, and arrange to export the function name (symbol) so other programs can link against the libvirt library and call the new function: =20 -``include/libvirt/libvirt-$MODULE.h.in src/libvirt_public.syms`` +* ``include/libvirt/libvirt-$MODULE.h.in`` +* ``src/libvirt_public.syms`` =20 Please consult our `coding style `__ guide on @@ -108,7 +110,7 @@ creation of a new struct type to represent the new driv= er type. =20 The driver structs are defined in: =20 -``src/driver-$MODULE.h`` +* ``src/driver-$MODULE.h`` =20 To define the internal API, first typedef the driver function prototype and then add a new field for it to the relevant driver struct. Then, @@ -142,7 +144,7 @@ driver implementation. In RFC 2119 vocabulary, this fun= ction: =20 The public API calls are implemented in: =20 -``src/libvirt-$MODULE.c`` +* ``src/libvirt-$MODULE.c`` =20 Implementing the remote protocol -------------------------------- @@ -156,7 +158,7 @@ Defining the wire protocol format =20 Defining the wire protocol involves making additions to: =20 -``src/remote/remote_protocol.x`` +* ``src/remote/remote_protocol.x`` =20 First, create two new structs for each new function that you're adding to the API. One struct describes the parameters to be passed to the @@ -174,7 +176,11 @@ protocol code. This must be done on a Linux host using= the GLibC rpcgen program. Other rpcgen versions may generate code which results in bogus compile time warnings. This regenerates the following files: =20 -``src/remote/remote_daemon_dispatch_stubs.h src/remote/remote_daem= on_dispatch.h src/remote/remote_daemon_dispatch.c src/remot= e/remote_protocol.c src/remote/remote_protocol.h`` +* ``src/remote/remote_daemon_dispatch_stubs.h`` +* ``src/remote/remote_daemon_dispatch.h`` +* ``src/remote/remote_daemon_dispatch.c`` +* ``src/remote/remote_protocol.c`` +* ``src/remote/remote_protocol.h`` =20 Implement the RPC client ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -182,7 +188,7 @@ Implement the RPC client Implementing the RPC client uses the rpcgen generated .h files. The remote method calls go in: =20 -``src/remote/remote_driver.c`` +* ``src/remote/remote_driver.c`` =20 Each remote method invocation does the following: =20 @@ -202,7 +208,7 @@ matter of deserializing the parameters passed in from t= he remote caller and passing them to the corresponding internal API function. The server side dispatchers are implemented in: =20 -``src/remote/remote_daemon_dispatch.c`` +* ``src/remote/remote_daemon_dispatch.c`` =20 Again, this step uses the .h files generated by make rpcgen. =20 @@ -210,7 +216,7 @@ After all three pieces of the remote protocol are compl= ete, and the generated files have been updated, it will be necessary to update the file: =20 -``src/remote_protocol-structs`` +* ``src/remote_protocol-structs`` =20 This file should only have new lines added; modifications to existing lines probably imply a backwards-incompatible API change. @@ -246,7 +252,8 @@ those pieces in place you can write the function implem= enting the virsh command. Finally, you need to add the new command to the commands[] array. The following files need changes: =20 -``tools/virsh-$MODULE.c tools/virsh.pod`` +* ``tools/virsh-$MODULE.c`` +* ``tools/virsh.pod`` =20 Implement the driver methods ---------------------------- --=20 2.43.2 _______________________________________________ Devel mailing list -- devel@lists.libvirt.org To unsubscribe send an email to devel-leave@lists.libvirt.org