[gjs: 2/6] macros: Add annotation for GJS_JSAPI_RETURN_CONVENTION

[Cosimo Cecchi <cosimoc src gnome org>]

commit 2d3f618c918e8d85712de413792d6760b96587bc
Author: Philip Chimento <philip endlessm com>
Date:   Wed Jul 31 15:06:09 2019 -0700

    macros: Add annotation for GJS_JSAPI_RETURN_CONVENTION
    
    Since I'm working on an analyzer plugin, let's add this annotation,
    hidden behind an ifdef guard for the Clang analyzer.

 gjs/macros.h | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)
---
diff --git a/gjs/macros.h b/gjs/macros.h
index a0090d1a..54383ce4 100644
--- a/gjs/macros.h
+++ b/gjs/macros.h
@@ -58,11 +58,17 @@
  * return value of false or nullptr means that an exception must be pending, or
  * else an uncatchable exception has been thrown.
  *
- * Same as %GJS_USE for now, but in the future this should be able to be used by
- * static analysis tools to do better consistency checks. It's also intended as
- * documentation for the programmer.
+ * It's intended for use by static analysis tools to do better consistency
+ * checks. If not using them, then it has the same effect as %GJS_USE above.
+ * It's also intended as documentation for the programmer.
  */
-#define GJS_JSAPI_RETURN_CONVENTION GJS_USE
+#ifdef __clang_analyzer__
+#    define GJS_JSAPI_RETURN_CONVENTION \
+        GJS_USE                         \
+        __attribute__((annotate("jsapi_return_convention")))
+#else
+#    define GJS_JSAPI_RETURN_CONVENTION GJS_USE
+#endif
 
 #ifdef __GNUC__
 #    define GJS_ALWAYS_INLINE __attribute__((always_inline))