[libadwaita] hacking: Use G_GNUC_WARN_UNUSED_RESULT in prototypes

[Alexander Mikhaylenko <alexm src gnome org>]

commit 42b5d40c7b16b737ba7cd38c0c82014a7368d92c
Author: Adrien Plazas <kekun plazas laposte net>
Date:   Thu May 27 09:24:13 2021 +0200

    hacking: Use G_GNUC_WARN_UNUSED_RESULT in prototypes
    
    This specifies G_GNUC_WARN_UNUSED_RESULT should be used in function
    prototypes.

 HACKING.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
---
diff --git a/HACKING.md b/HACKING.md
index 73725775..81e02a8c 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -101,6 +101,37 @@ ADW_AVAILABLE_IN_ALL
 void adw_foo_frobnicate (AdwFoo *self);
 ```
 
+If the function transfers a new handle to a resource, like a reference, a
+floating reference, a file handle, or any other kind of handle that would result
+into a resource leak if ignored, add `G_GNUC_WARN_UNUSED_RESULT` after the
+closing parenthesis.
+No need to add `G_GNUC_WARN_UNUSED_RESULT` when the caller is guaranteed to have
+a handle to the resource, e.g. in methods incrementing a reference counter.
+
+*Good*:
+
+```c
+ADW_AVAILABLE_IN_ALL
+AdwFoo *adw_foo_new (void) G_GNUC_WARN_UNUSED_RESULT;
+ADW_AVAILABLE_IN_ALL
+AdwFoo *adw_foo_ref (AdwFoo *self);
+
+ADW_AVAILABLE_IN_ALL
+char *adw_foo_to_string (AdwFoo *self) G_GNUC_WARN_UNUSED_RESULT;
+```
+
+*Bad*:
+
+```c
+ADW_AVAILABLE_IN_ALL
+AdwFoo *adw_foo_new (void);
+ADW_AVAILABLE_IN_ALL
+AdwFoo *adw_foo_ref (AdwFoo *self) G_GNUC_WARN_UNUSED_RESULT;
+
+ADW_AVAILABLE_IN_ALL
+char *adw_foo_to_string (AdwFoo *self);
+```
+
 ### Braces
 
 Everything besides functions and structs have the opening curly brace on the same line.