[libvirt PATCH 1/2] docs: Convert existing tables to list-table

Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- docs/coding-style.rst | 53 +++++++++++------- docs/glib-adoption.rst | 123 +++++++++++++++++++++++++++-------------- 2 files changed, 114 insertions(+), 62 deletions(-) diff --git a/docs/coding-style.rst b/docs/coding-style.rst index 151ea87b6a..15c3a0b22d 100644 --- a/docs/coding-style.rst +++ b/docs/coding-style.rst @@ -547,27 +547,38 @@ Attribute annotations Use the following annotations to help the compiler and/or static analysis tools understand the code better: -+-------------------------------+------------------------------------------------------------+ -| Macro | Meaning | -+===============================+============================================================+ -| ``ATTRIBUTE_NONNULL`` | passing NULL for this parameter is not allowed | -+-------------------------------+------------------------------------------------------------+ -| ``ATTRIBUTE_PACKED`` | force a structure to be packed | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_FALLTHROUGH`` | allow code reuse by multiple switch cases | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NO_INLINE`` | the function is mocked in the test suite | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NORETURN`` | the function never returns | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_NULL_TERMINATED`` | last parameter must be NULL | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_PRINTF`` | validate that the formatting string matches parameters | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_UNUSED`` | parameter is unused in this implementation of the function | -+-------------------------------+------------------------------------------------------------+ -| ``G_GNUC_WARN_UNUSED_RESULT`` | the return value must be checked | -+-------------------------------+------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + + * - Macro + - Meaning + + * - ``ATTRIBUTE_NONNULL`` + - passing NULL for this parameter is not allowed + + * - ``ATTRIBUTE_PACKED`` + - force a structure to be packed + + * - ``G_GNUC_FALLTHROUGH`` + - allow code reuse by multiple switch cases + + * - ``G_GNUC_NO_INLINE`` + - the function is mocked in the test suite + + * - ``G_GNUC_NORETURN`` + - the function never returns + + * - ``G_GNUC_NULL_TERMINATED`` + - last parameter must be NULL + + * - ``G_GNUC_PRINTF`` + - validate that the formatting string matches parameters + + * - ``G_GNUC_UNUSED`` + - parameter is unused in this implementation of the function + + * - ``G_GNUC_WARN_UNUSED_RESULT`` + - the return value must be checked File handling ------------- diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst index 62ddd7c61d..a5dca47f5e 100644 --- a/docs/glib-adoption.rst +++ b/docs/glib-adoption.rst @@ -53,44 +53,85 @@ The following libvirt APIs have been deleted already: ``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`` | | -+-------------------------------+--------------------------------------+-------------------------------------------+ +.. list-table:: + :header-rows: 1 + + * - 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`` + - -- 2.25.4