From 900e54ed2e3b21a3b828384e16333183d5b7e314 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A1n=20Tomko?= <jtomko@redhat.com>
Date: Thu, 24 Sep 2020 13:50:49 +0200
Subject: [PATCH] docs: glib-adoption: split into sections
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Although all the mentioned functions deal with
allocation, replacing the pure allocation
functions is easier than converting code to
use GArrays.

Split them out to encourage usage of GLib
allocation APIs even at the cost of them
being combined with VIR_*ELEMENT APIs.

Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
---
 docs/glib-adoption.rst | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst
index 91d0c66d91..4c389d7a34 100644
--- a/docs/glib-adoption.rst
+++ b/docs/glib-adoption.rst
@@ -14,14 +14,21 @@ the GLib APIs straight away where possible.
 The following is a list of libvirt APIs that should no longer be
 used in new code, and their suggested GLib replacements:
 
-``VIR_ALLOC``, ``VIR_REALLOC``, ``VIR_RESIZE_N``, ``VIR_EXPAND_N``, ``VIR_SHRINK_N``, ``VIR_FREE``, ``VIR_APPEND_ELEMENT``, ``VIR_INSERT_ELEMENT``, ``VIR_DELETE_ELEMENT``
+Memory allocation
+   ``VIR_ALLOC``, ``VIR_REALLOC``, ``VIR_RESIZE_N``,
+   ``VIR_EXPAND_N``, ``VIR_SHRINK_N``, ``VIR_FREE``
+
    Prefer the GLib APIs ``g_new0``/``g_renew``/ ``g_free`` in most
    cases. There should rarely be a need to use
-   ``g_malloc``/``g_realloc``. Instead of using plain C arrays, it
-   is preferrable to use one of the GLib types, ``GArray``,
-   ``GPtrArray`` or ``GByteArray``. These all use a struct to
-   track the array memory and size together and efficiently
-   resize. **NEVER MIX** use of the classic libvirt memory
-   allocation APIs and GLib APIs within a single method. Keep the
-   style consistent, converting existing code to GLib style in a
-   separate, prior commit.
+   ``g_malloc``/``g_realloc``. **NEVER MIX** use of the classic
+   libvirt memory allocation APIs and GLib APIs within a single
+   method. Keep the style consistent, converting existing code to
+   GLib style in a separate, prior commit.
+
+Array operations
+   ``VIR_APPEND_ELEMENT``, ``VIR_INSERT_ELEMENT``, ``VIR_DELETE_ELEMENT``
+
+   Instead of using plain C arrays, it is preferrable to use one of
+   the GLib types, ``GArray``, ``GPtrArray`` or ``GByteArray``.
+   These all use a struct to track the array memory and size
+   together and efficiently resize.