js: Introduce annotations for using return values

This introduces two annotations to functions. GJS_USE is a macro for GCC
and Clang's "warn_unused_result" annotation, meaning that the return
value of a function must not be ignored. This allows us to catch some
cases where we are neglecting to do error checking.

The second annotation is GJS_JSAPI_RETURN_CONVENTION which for now is
identical to GJS_USE, but could be made into a custom annotation in the
future which a static analyzer plugin could use to enforce further checks
at compile time. The "JSAPI return convention" is valid on functions that
return bool or a pointer type, and whose first parameter is JSContext*. If
false or nullptr is returned, then an exception must be pending at return
time on the passed-in JSContext. If true or a non-nullptr value is
returned, then no exception must be pending.

This commit only has the addition of the attributes, and a few fixes
mandated by the autoformatter, so it can be reviewed "lightly".

1 files changed, 6 insertions, 0 deletions

diff --git a/gi/param.h b/gi/param.h
index f5ed5467..adb4657c 100644
--- a/gi/param.h
+++ b/gi/param.h
@@ -27,19 +27,25 @@
 #include <stdbool.h>
 #include <glib.h>
 #include <girepository.h>
+
 #include "gjs/jsapi-util.h"
+#include "gjs/macros.h"
 
 G_BEGIN_DECLS
 
+GJS_JSAPI_RETURN_CONVENTION
 bool gjs_define_param_class(JSContext       *context,
                             JS::HandleObject in_object);
 
+GJS_JSAPI_RETURN_CONVENTION
 GParamSpec *gjs_g_param_from_param (JSContext       *context,
                                     JS::HandleObject obj);
 
+GJS_JSAPI_RETURN_CONVENTION
 JSObject*   gjs_param_from_g_param     (JSContext  *context,
                                         GParamSpec *param);
 
+GJS_USE
 bool        gjs_typecheck_param(JSContext       *context,
                                 JS::HandleObject obj,
                                 GType            expected_type,