docs: glib-adoption: split into sections

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>

diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst
index 91d0c66d9135c41b82adbb7406bad22c7726ac42..4c389d7a343ebda3dc0a824d63ec3b9f50b66a00 100644 (file)
--- 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.