From e30c787a0cef6cc7dccb4da730b6163e1d1c485b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A1n=20Tomko?= <jtomko@redhat.com>
Date: Fri, 18 Oct 2019 23:12:19 +0200
Subject: [PATCH] docs: hacking: mention compiler annotations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mention all the __attribute__ annotations we use to make the compiler
and/or the static analysis tools understand the code better.

Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
---
 docs/hacking.html.in | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index ae4d14e7b7..f3ad43eee7 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -985,6 +985,25 @@ BAD:
       it points to, or it is aliased to another pointer that is.
     </p>
 
+    <h2><a id="attribute_annotations">Attribute annotations</a></h2>
+    <p>
+      Use the following annotations to help the compiler and/or static
+      analysis tools understand the code better:
+    </p>
+
+    <table class="top_table">
+        <tr><th>Macro</th><th>Meaning</th></tr>
+        <tr><td><code>ATTRIBUTE_NONNULL</code></td><td>passing NULL for this parameter is not allowed</td></tr>
+        <tr><td><code>ATTRIBUTE_PACKED</code></td><td>force a structure to be packed</td></tr>
+        <tr><td><code>G_GNUC_FALLTHROUGH</code></td><td>allow code reuse by multiple switch cases</td></tr>
+        <tr><td><code>G_GNUC_NO_INLINE</code></td><td>the function is mocked in the test suite</td></tr>
+        <tr><td><code>G_GNUC_NORETURN</code></td><td>the function never returns</td></tr>
+        <tr><td><code>G_GNUC_NULL_TERMINATED</code></td><td>last parameter must be NULL</td></tr>
+        <tr><td><code>G_GNUC_PRINTF</code></td><td>validate that the formatting string matches parameters</td></tr>
+        <tr><td><code>G_GNUC_UNUSED</code></td><td>parameter is unused in this implementation of the function</td></tr>
+        <tr><td><code>G_GNUC_WARN_UNUSED_RESULT</code></td><td>the return value must be checked</td></tr>
+    </table>
+
     <h2><a id="glib">Adoption of GLib APIs</a></h2>
 
     <p>
-- 
GitLab