From c780be11d6dabfc4ee8edfa845142c691d49dc59 Mon Sep 17 00:00:00 2001 From: Andrea Bolognani Date: Mon, 19 Feb 2024 11:39:28 +0100 Subject: [PATCH] docs: Format lists of files better Signed-off-by: Andrea Bolognani Reviewed-by: Michal Privoznik --- 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: -``src/conf/schemas/domaincommon.rng docs/formatdomain.rst`` +* ``src/conf/schemas/domaincommon.rng`` +* ``docs/formatdomain.rst`` 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: -``include/libvirt/libvirt-$MODULE.h.in src/libvirt_public.syms`` +* ``include/libvirt/libvirt-$MODULE.h.in`` +* ``src/libvirt_public.syms`` Please consult our `coding style `__ guide on @@ -108,7 +110,7 @@ creation of a new struct type to represent the new driver type. The driver structs are defined in: -``src/driver-$MODULE.h`` +* ``src/driver-$MODULE.h`` 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 function: The public API calls are implemented in: -``src/libvirt-$MODULE.c`` +* ``src/libvirt-$MODULE.c`` Implementing the remote protocol -------------------------------- @@ -156,7 +158,7 @@ Defining the wire protocol format Defining the wire protocol involves making additions to: -``src/remote/remote_protocol.x`` +* ``src/remote/remote_protocol.x`` 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: -``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`` +* ``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`` 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: -``src/remote/remote_driver.c`` +* ``src/remote/remote_driver.c`` Each remote method invocation does the following: @@ -202,7 +208,7 @@ matter of deserializing the parameters passed in from the remote caller and passing them to the corresponding internal API function. The server side dispatchers are implemented in: -``src/remote/remote_daemon_dispatch.c`` +* ``src/remote/remote_daemon_dispatch.c`` Again, this step uses the .h files generated by make rpcgen. @@ -210,7 +216,7 @@ After all three pieces of the remote protocol are complete, and the generated files have been updated, it will be necessary to update the file: -``src/remote_protocol-structs`` +* ``src/remote_protocol-structs`` 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 implementing the virsh command. Finally, you need to add the new command to the commands[] array. The following files need changes: -``tools/virsh-$MODULE.c tools/virsh.pod`` +* ``tools/virsh-$MODULE.c`` +* ``tools/virsh.pod`` Implement the driver methods ----------------------------