docs: Add glib-adoption.rst

This part is very specific and doesn't quite fit into the "coding
style" section, so let's move it to its own page.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

docs/glib-adoption.rst

+=====================
+Adoption of GLib APIs
+=====================
+
+Libvirt has adopted use of the `GLib
+library <https://developer.gnome.org/glib/stable/>`__. Due to
+libvirt's long history of development, there are many APIs in
+libvirt, for which GLib provides an alternative solution. The
+general rule to follow is that the standard GLib solution will be
+preferred over historical libvirt APIs. Existing code will be
+ported over to use GLib APIs over time, but new code should use
+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``
+   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.
+``virStrerror``
+   The GLib ``g_strerror()`` function should be used instead,
+   which has a simpler calling convention as an added benefit.
+
+The following libvirt APIs have been deleted already:
+
+``VIR_AUTOPTR``, ``VIR_AUTOCLEAN``, ``VIR_AUTOFREE``
+   The GLib macros ``g_autoptr``, ``g_auto`` and ``g_autofree``
+   must be used instead in all new code. In existing code, the
+   GLib macros must never be mixed with libvirt macros within a
+   method, nor should they be mixed with ``VIR_FREE``. If
+   introducing GLib macros to an existing method, any use of
+   libvirt macros must be converted in an independent commit.
+``VIR_DEFINE_AUTOPTR_FUNC``, ``VIR_DEFINE_AUTOCLEAN_FUNC``
+   The GLib macros ``G_DEFINE_AUTOPTR_CLEANUP_FUNC`` and
+   ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC`` must be used in all new
+   code. Existing code should be converted to the new macros where
+   relevant. It is permissible to use ``g_autoptr``, ``g_auto`` on
+   an object whose cleanup function is declared with the libvirt
+   macros and vice-versa.
+``VIR_AUTOUNREF``
+   The GLib macros ``g_autoptr`` and
+   ``G_DEFINE_AUTOPTR_CLEANUP_FUNC`` should be used to manage
+   autoclean of virObject classes. This matches usage with GObject
+   classes.
+``VIR_STRDUP``, ``VIR_STRNDUP``
+   Prefer the GLib APIs ``g_strdup`` and ``g_strndup``.
+
++-------------------------------+--------------------------------------+-------------------------------------------+
+| deleted version               | GLib version                         | Notes                                     |
++===============================+======================================+===========================================+
+| ``VIR_AUTOPTR``               | ``g_autoptr``                        |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``VIR_AUTOCLEAN``             | ``g_auto``                           |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``VIR_AUTOFREE``              | ``g_autofree``                       | The GLib version does not use parentheses |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``VIR_AUTOUNREF``             | ``g_autoptr``                        | The cleanup function needs to be defined  |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``VIR_DEFINE_AUTOPTR_FUNC``   | ``G_DEFINE_AUTOPTR_CLEANUP_FUNC``    |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``VIR_DEFINE_AUTOCLEAN_FUNC`` | ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC`` |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``VIR_STEAL_PTR``             | ``g_steal_pointer``                  | ``a = f(&b)`` instead of ``f(a, b)``      |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``VIR_RETURN_PTR``            | ``return g_steal_pointer``           |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``ARRAY_CARDINALITY``         | ``G_N_ELEMENTS``                     |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``ATTRIBUTE_FALLTHROUGH``     | ``G_GNUC_FALLTHROUGH``               |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``ATTRIBUTE_FMT_PRINTF``      | ``G_GNUC_PRINTF``                    |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``ATTRIBUTE_NOINLINE``        | ``G_GNUC_NO_INLINE``                 |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``ATTRIBUTE_NORETURN``        | ``G_GNUC_NORETURN``                  |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``ATTRIBUTE_RETURN_CHECK``    | ``G_GNUC_WARN_UNUSED_RESULT``        |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``ATTRIBUTE_SENTINEL``        | ``G_GNUC_NULL_TERMINATED``           |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``ATTRIBUTE_UNUSED``          | ``G_GNUC_UNUSED``                    |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``VIR_STRDUP``                | ``g_strdup``                         |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``VIR_STRNDUP``               | ``g_strndup``                        |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+
+| ``virStrerror``               | ``g_strerror``                       |                                           |
++-------------------------------+--------------------------------------+-------------------------------------------+

docs/hacking.rst

@@ -921,102 +921,6 @@ analysis tools understand the code better:
 | ``G_GNUC_WARN_UNUSED_RESULT`` | the return value must be checked                           |
 +-------------------------------+------------------------------------------------------------+
 
-Adoption of GLib APIs
----------------------
-
-Libvirt has adopted use of the `GLib
-library <https://developer.gnome.org/glib/stable/>`__. Due to
-libvirt's long history of development, there are many APIs in
-libvirt, for which GLib provides an alternative solution. The
-general rule to follow is that the standard GLib solution will be
-preferred over historical libvirt APIs. Existing code will be
-ported over to use GLib APIs over time, but new code should use
-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``
-   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.
-``virStrerror``
-   The GLib ``g_strerror()`` function should be used instead,
-   which has a simpler calling convention as an added benefit.
-
-The following libvirt APIs have been deleted already:
-
-``VIR_AUTOPTR``, ``VIR_AUTOCLEAN``, ``VIR_AUTOFREE``
-   The GLib macros ``g_autoptr``, ``g_auto`` and ``g_autofree``
-   must be used instead in all new code. In existing code, the
-   GLib macros must never be mixed with libvirt macros within a
-   method, nor should they be mixed with ``VIR_FREE``. If
-   introducing GLib macros to an existing method, any use of
-   libvirt macros must be converted in an independent commit.
-``VIR_DEFINE_AUTOPTR_FUNC``, ``VIR_DEFINE_AUTOCLEAN_FUNC``
-   The GLib macros ``G_DEFINE_AUTOPTR_CLEANUP_FUNC`` and
-   ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC`` must be used in all new
-   code. Existing code should be converted to the new macros where
-   relevant. It is permissible to use ``g_autoptr``, ``g_auto`` on
-   an object whose cleanup function is declared with the libvirt
-   macros and vice-versa.
-``VIR_AUTOUNREF``
-   The GLib macros ``g_autoptr`` and
-   ``G_DEFINE_AUTOPTR_CLEANUP_FUNC`` should be used to manage
-   autoclean of virObject classes. This matches usage with GObject
-   classes.
-``VIR_STRDUP``, ``VIR_STRNDUP``
-   Prefer the GLib APIs ``g_strdup`` and ``g_strndup``.
-
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| deleted version               | GLib version                         | Notes                                     |
-+===============================+======================================+===========================================+
-| ``VIR_AUTOPTR``               | ``g_autoptr``                        |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_AUTOCLEAN``             | ``g_auto``                           |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_AUTOFREE``              | ``g_autofree``                       | The GLib version does not use parentheses |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_AUTOUNREF``             | ``g_autoptr``                        | The cleanup function needs to be defined  |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_DEFINE_AUTOPTR_FUNC``   | ``G_DEFINE_AUTOPTR_CLEANUP_FUNC``    |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_DEFINE_AUTOCLEAN_FUNC`` | ``G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC`` |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_STEAL_PTR``             | ``g_steal_pointer``                  | ``a = f(&b)`` instead of ``f(a, b)``      |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_RETURN_PTR``            | ``return g_steal_pointer``           |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ARRAY_CARDINALITY``         | ``G_N_ELEMENTS``                     |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_FALLTHROUGH``     | ``G_GNUC_FALLTHROUGH``               |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_FMT_PRINTF``      | ``G_GNUC_PRINTF``                    |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_NOINLINE``        | ``G_GNUC_NO_INLINE``                 |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_NORETURN``        | ``G_GNUC_NORETURN``                  |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_RETURN_CHECK``    | ``G_GNUC_WARN_UNUSED_RESULT``        |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_SENTINEL``        | ``G_GNUC_NULL_TERMINATED``           |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``ATTRIBUTE_UNUSED``          | ``G_GNUC_UNUSED``                    |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_STRDUP``                | ``g_strdup``                         |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``VIR_STRNDUP``               | ``g_strndup``                        |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-| ``virStrerror``               | ``g_strerror``                       |                                           |
-+-------------------------------+--------------------------------------+-------------------------------------------+
-
 File handling
 -------------