From nobody Thu May 2 21:32:18 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) client-ip=207.211.31.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1588872937; cv=none; d=zohomail.com; s=zohoarc; b=BX3GQ8q/5e8GyhXPcZf0Mvce/n6gBze6aX6NWuItoof4mv9hxZLUnm0f4PTtJqyJoGK9UuIIyZRUG9xvBuIyKAeUaQB6XdRMZCjxQ8h6qEJMQwmvPq/9A9PvYVlJ5HbvxIYbq2RagYTQuheu7UXfbyLk8olk63Mr7MtQW//YdRk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1588872937; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=+wIK6BssvJ1+4vzgfOdTfgjhwAEutk0toiE+d8YTh0U=; b=fFWQ8RGCO0NjObuk6gSPgmchfrAwNr2ty/S3633nEWsPV/wIF7/SGlulYib/SqKR91Mti6O6ZbiepbvTCjCNlzw32FUnEC9Re2BGS8W2gIpHDdGen31JsVeK39dN0oGGfOumwOjFiHUQGdEoEwBwaWW8FPgkYzG0pMfTlf+rluk= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.120]) by mx.zohomail.com with SMTPS id 1588872937232455.7701594378598; Thu, 7 May 2020 10:35:37 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-471-r6KeWOnEPhCPIGUOMKXgbw-1; Thu, 07 May 2020 13:35:33 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id E3E4A107ACCD; Thu, 7 May 2020 17:35:27 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 986782BFF9; Thu, 7 May 2020 17:35:27 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id A42461809542; Thu, 7 May 2020 17:35:26 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 047HZP6O011481 for ; Thu, 7 May 2020 13:35:25 -0400 Received: by smtp.corp.redhat.com (Postfix) id A4AE9707B0; Thu, 7 May 2020 17:35:25 +0000 (UTC) Received: from kinshicho.usersys.redhat.com (unknown [10.40.194.140]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 68EB77055D for ; Thu, 7 May 2020 17:35:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1588872935; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=+wIK6BssvJ1+4vzgfOdTfgjhwAEutk0toiE+d8YTh0U=; b=SsNSi9xM23S0s/NEjxDYg5TtJRZV73qiJMe7/gcWEN0XrW3GOcFjtEtcb5gJvpnf/lx2zL KZ/LX3s3flE86S2IN0YBmxbcJbhbzxAucVfSa/eZG0b3NmEXrdgqSpDCohXTQmE5ypx4Un q7yAYLQQv9OYQwh7HLGh553IJiO5Zfo= X-MC-Unique: r6KeWOnEPhCPIGUOMKXgbw-1 From: Andrea Bolognani To: libvir-list@redhat.com Subject: [libvirt PATCH v2 1/3] docs: Drop glib-adoption.rst Date: Thu, 7 May 2020 19:35:15 +0200 Message-Id: <20200507173517.934216-2-abologna@redhat.com> In-Reply-To: <20200507173517.934216-1-abologna@redhat.com> References: <20200507173517.934216-1-abologna@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" It's been more than six months since we adopted GLib and we've been pretty aggressive at replacing our homegrown APIs with more standard ones, so by now most of the symbols mentioned in this document haven't been around for quite a long time already. Signed-off-by: Andrea Bolognani Reviewed-by: Daniel P. Berrang=C3=A9 --- docs/glib-adoption.rst | 96 ------------------------------------------ docs/hacking.rst | 1 - 2 files changed, 97 deletions(-) delete mode 100644 docs/glib-adoption.rst diff --git a/docs/glib-adoption.rst b/docs/glib-adoption.rst deleted file mode 100644 index 62ddd7c61d..0000000000 --- a/docs/glib-adoption.rst +++ /dev/null @@ -1,96 +0,0 @@ -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D -Adoption of GLib APIs -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -Libvirt has adopted use of the `GLib -library `__. 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 | N= otes | -+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ -| ``VIR_AUTOPTR`` | ``g_autoptr`` | = | -+-------------------------------+--------------------------------------+--= -----------------------------------------+ -| ``VIR_AUTOCLEAN`` | ``g_auto`` | = | -+-------------------------------+--------------------------------------+--= -----------------------------------------+ -| ``VIR_AUTOFREE`` | ``g_autofree`` | T= he GLib version does not use parentheses | -+-------------------------------+--------------------------------------+--= -----------------------------------------+ -| ``VIR_AUTOUNREF`` | ``g_autoptr`` | T= he 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 =3D 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`` | = | -+-------------------------------+--------------------------------------+--= -----------------------------------------+ diff --git a/docs/hacking.rst b/docs/hacking.rst index 1c64146c5d..61ae6452e1 100644 --- a/docs/hacking.rst +++ b/docs/hacking.rst @@ -75,5 +75,4 @@ you also take a look at the following documents: - `Programming languages `__ - `Developer tooling `__ - `Advanced test suite usage `__ -- `Adoption of GLib APIs `__ - `Committer guidelines `__ --=20 2.25.4 From nobody Thu May 2 21:32:18 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) client-ip=205.139.110.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1588872937; cv=none; d=zohomail.com; s=zohoarc; b=m0dF4O2M2oa4vWs/hefoMstLpIcVNUjAa3RnO3dT/n9XhX0apbMjiLn5LXiBysdAdwGrbjSK7yoUEk9kmk0kPPHD8OJ4LOT4YJnCbG8uMJqIHDipQerokAiy2DFfCAs5sjFVA+TQUgcmMNH+3JQw1BQL48kjcNViKXcwnXUQsXY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1588872937; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=OVxR+EJsP/lTwKZ7s+J1rJpB/KYiRU91SwTZiOZUaLM=; b=EuHJEiZLLzbgtloHQPi+bpL/HLjndttxRsKLX4RsOrslM2oD+mPqqdM++VQLskr638jNvVQQCjuIwhFhw6hItwU4uARzUiyywEuSAEv+PZf6ivdhXF2AdYhlYRnwKPWYH6zgmssRWPfWVXNcgILFhMrws4q9QFyAEV0Cz0E8jcc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) by mx.zohomail.com with SMTPS id 1588872937797590.3872498560668; Thu, 7 May 2020 10:35:37 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-408-mjgn0jiBN6GZr8R-zide-g-1; Thu, 07 May 2020 13:35:33 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 79C7C835B44; Thu, 7 May 2020 17:35:28 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 494025C1B0; Thu, 7 May 2020 17:35:28 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id CE2ED4E565; Thu, 7 May 2020 17:35:27 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 047HZQmw011490 for ; Thu, 7 May 2020 13:35:26 -0400 Received: by smtp.corp.redhat.com (Postfix) id D0DD9707A5; Thu, 7 May 2020 17:35:26 +0000 (UTC) Received: from kinshicho.usersys.redhat.com (unknown [10.40.194.140]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 491EC7055D for ; Thu, 7 May 2020 17:35:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1588872936; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=OVxR+EJsP/lTwKZ7s+J1rJpB/KYiRU91SwTZiOZUaLM=; b=fnfuEU7GLL65CDJYCNYRi1m2Yg+tppUenErYtg0K+x43/EGl4n5Ll82OpCrMJG4u1I0ZJb IvbyNRghNmyUt/+h9XF3OANNgXxiuRmJrYFq3GnNYAhtROteoX7PqBy1fqkHoAKLY7//gC EMaP3cLiRbN6gLA9nE+6XI1trReim5A= X-MC-Unique: mjgn0jiBN6GZr8R-zide-g-1 From: Andrea Bolognani To: libvir-list@redhat.com Subject: [libvirt PATCH v2 2/3] docs: Use definition list instead of table in coding style Date: Thu, 7 May 2020 19:35:16 +0200 Message-Id: <20200507173517.934216-3-abologna@redhat.com> In-Reply-To: <20200507173517.934216-1-abologna@redhat.com> References: <20200507173517.934216-1-abologna@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" This format is much easier to tweak and update. Signed-off-by: Andrea Bolognani Reviewed-by: Daniel P. Berrang=C3=A9 --- docs/coding-style.rst | 47 ++++++++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 21 deletions(-) diff --git a/docs/coding-style.rst b/docs/coding-style.rst index 151ea87b6a..03b89c86e5 100644 --- a/docs/coding-style.rst +++ b/docs/coding-style.rst @@ -547,27 +547,32 @@ Attribute annotations Use the following annotations to help the compiler and/or static analysis tools understand the code better: =20 -+-------------------------------+-----------------------------------------= -------------------+ -| Macro | Meaning = | -+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ -| ``ATTRIBUTE_NONNULL`` | passing NULL for this parameter is not a= llowed | -+-------------------------------+-----------------------------------------= -------------------+ -| ``ATTRIBUTE_PACKED`` | force a structure to be packed = | -+-------------------------------+-----------------------------------------= -------------------+ -| ``G_GNUC_FALLTHROUGH`` | allow code reuse by multiple switch case= s | -+-------------------------------+-----------------------------------------= -------------------+ -| ``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 matc= hes parameters | -+-------------------------------+-----------------------------------------= -------------------+ -| ``G_GNUC_UNUSED`` | parameter is unused in this implementati= on of the function | -+-------------------------------+-----------------------------------------= -------------------+ -| ``G_GNUC_WARN_UNUSED_RESULT`` | the return value must be checked = | -+-------------------------------+-----------------------------------------= -------------------+ +``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 =20 File handling ------------- --=20 2.25.4 From nobody Thu May 2 21:32:18 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) client-ip=205.139.110.61; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1588872947; cv=none; d=zohomail.com; s=zohoarc; b=nvRIv5LAYXexSxCMl3uU5PD42Q1t1Y89JWMYv2RNhtLcf0lZEGqrnz/da3FAcQEMimkAeeuk+uGMjy2zwgduKD9d1w7swN8IwYxde1+rIuNZoppC7ofk0QR9btUDmNfTVmwN5PfHdaAfWixX5UgwIzR/Kj9TTRkpUnzg6HxQ+DQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1588872947; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=oBdxQ/T4mtFGWXbyHEwvWaZYw1tBV5S8+lbf2nwkTL4=; b=DfIajMXKWqNtFQ8S3hsdsrMkreaDhh6vZmYYffHkxB1fpn3VFmHAucdZwYWMVl+imJk/EWZHZYIV4zqTC7IIjFf5FwohFD8sxOvDe+6V2HgFwVTg/qIzMuhz+HxBd7aPbhd2QnBKY6WCP8jxzoekWux0PU9zenjphPdLVM61efY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-1.mimecast.com [205.139.110.61]) by mx.zohomail.com with SMTPS id 1588872947455640.8589113997118; Thu, 7 May 2020 10:35:47 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-22-G9MMOsNjN_i4-pn_UaiSNg-1; Thu, 07 May 2020 13:35:43 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 6A6CF835B42; Thu, 7 May 2020 17:35:38 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 39D1125277; Thu, 7 May 2020 17:35:38 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id E123C4E982; Thu, 7 May 2020 17:35:37 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 047HZSdF011501 for ; Thu, 7 May 2020 13:35:28 -0400 Received: by smtp.corp.redhat.com (Postfix) id 5649F7055D; Thu, 7 May 2020 17:35:28 +0000 (UTC) Received: from kinshicho.usersys.redhat.com (unknown [10.40.194.140]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 79A9E707A5 for ; Thu, 7 May 2020 17:35:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1588872946; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=oBdxQ/T4mtFGWXbyHEwvWaZYw1tBV5S8+lbf2nwkTL4=; b=MyXAtgfiAiR//1GFJR95aper7h6+hxUVxzWWq/oh1WWMkK6OOCUEwm3ViMQtD/kzu3lemw XOIG53sEcU2IYf+ZUVA0HStxwefU6LMUCX0uVF4SIDZUhnQ7jW15SUMhrWa0JppsI94NGR Ts6B0K0bLxt1WtA9V8NnWjSvackbGVc= X-MC-Unique: G9MMOsNjN_i4-pn_UaiSNg-1 From: Andrea Bolognani To: libvir-list@redhat.com Subject: [libvirt PATCH v2 3/3] docs: Document list-tables as recommended Date: Thu, 7 May 2020 19:35:17 +0200 Message-Id: <20200507173517.934216-4-abologna@redhat.com> In-Reply-To: <20200507173517.934216-1-abologna@redhat.com> References: <20200507173517.934216-1-abologna@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Signed-off-by: Andrea Bolognani Reviewed-by: Daniel P. Berrang=C3=A9 --- docs/styleguide.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/styleguide.rst b/docs/styleguide.rst index 3162868fb7..34c5b1573a 100644 --- a/docs/styleguide.rst +++ b/docs/styleguide.rst @@ -77,6 +77,26 @@ which allows for 6 levels of headings Heading 6 ^^^^^^^^^ =20 +Tables +=3D=3D=3D=3D=3D=3D + +Tables should be created using the ``list-table`` directive whenever +possible, as in + +:: + + .. list-table:: + :header-rows: 1 + + * - Option + - Description + + * - ``foo_enabled`` + - Whether or not ``foo`` should be enabled + + * - ``bar_user`` + - Which user to run ``bar`` as + Manual pages =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.25.4