docs: improve documentation of enums, flags and errors

3 files changed, 38 insertions, 12 deletions

diff --git a/build-aux/templates/qmi-enum-types-template.c b/build-aux/templates/qmi-enum-types-template.c
index 7f12c2c..db29eec 100644
--- a/build-aux/templates/qmi-enum-types-template.c
+++ b/build-aux/templates/qmi-enum-types-template.c
@@ -17,9 +17,9 @@ static const G@Type@Value @enum_name@_values[] = {
 };
 
 /* Define type-specific symbols */
-#undef IS_ENUM
-#undef IS_FLAGS
-#define IS_@TYPE@
+#undef __QMI_IS_ENUM__
+#undef __QMI_IS_FLAGS__
+#define __QMI_IS_@TYPE@__
 
 GType
 @enum_name@_get_type (void)
@@ -39,7 +39,15 @@ GType
 /* Enum-specific method to get the value as a string.
  * We get the nick of the GEnumValue. Note that this will be
  * valid even if the GEnumClass is not referenced anywhere. */
-#if defined IS_ENUM
+#if defined __QMI_IS_ENUM__
+/**
+ * @enum_name@_get_string:
+ * @val: a @EnumName@.
+ *
+ * Gets the nickname string for the #@EnumName@ specified at @val.
+ *
+ * Returns: (transfer none): a string with the nickname, or %NULL if not found. Do not free the returned value.
+ */
 const gchar *
 @enum_name@_get_string (@EnumName@ val)
 {
@@ -52,13 +60,22 @@ const gchar *
 
     return NULL;
 }
-#endif /* IS_ENUM */
+#endif /* __QMI_IS_ENUM__ */
 
 /* Flags-specific method to build a string with the given mask.
  * We get a comma separated list of the nicks of the GFlagsValues.
  * Note that this will be valid even if the GFlagsClass is not referenced
  * anywhere. */
-#if defined IS_FLAGS
+#if defined __QMI_IS_FLAGS__
+/**
+ * @enum_name@_build_string_from_mask:
+ * @mask: bitmask of @EnumName@ values.
+ *
+ * Builds a string containing a comma-separated list of nicknames for
+ * each #@EnumName@ in @mask.
+ *
+ * Returns: (transfer full): a string with the list of nicknames, or %NULL if none given. The returned value should be freed with g_free().
+ */
 gchar *
 @enum_name@_build_string_from_mask (@EnumName@ mask)
 {
@@ -96,7 +113,7 @@ gchar *
 
     return (str ? g_string_free (str, FALSE) : NULL);
 }
-#endif /* IS_FLAGS */
+#endif /* __QMI_IS_FLAGS__ */
 
 /*** END value-tail ***/
 
diff --git a/build-aux/templates/qmi-enum-types-template.h b/build-aux/templates/qmi-enum-types-template.h
index 13db2a6..bdcd4e7 100644
--- a/build-aux/templates/qmi-enum-types-template.h
+++ b/build-aux/templates/qmi-enum-types-template.h
@@ -15,15 +15,15 @@ GType @enum_name@_get_type (void) G_GNUC_CONST;
 #define @ENUMPREFIX@_TYPE_@ENUMSHORT@ (@enum_name@_get_type ())
 
 /* Define type-specific symbols */
-#undef IS_ENUM
-#undef IS_FLAGS
-#define IS_@TYPE@
+#undef __QMI_IS_ENUM__
+#undef __QMI_IS_FLAGS_
+#define __QMI_IS_@TYPE@__
 
-#if defined IS_ENUM
+#if defined __QMI_IS_ENUM__
 const gchar *@enum_name@_get_string (@EnumName@ val);
 #endif
 
-#if defined IS_FLAGS
+#if defined __QMI_IS_FLAGS__
 gchar *@enum_name@_build_string_from_mask (@EnumName@ mask);
 #endif
 
diff --git a/build-aux/templates/qmi-flags64-types-template.c b/build-aux/templates/qmi-flags64-types-template.c
index e8feb96..c1c5491 100644
--- a/build-aux/templates/qmi-flags64-types-template.c
+++ b/build-aux/templates/qmi-flags64-types-template.c
@@ -22,6 +22,15 @@ static const GFlags64Value @enum_name@_values[] = {
     { 0, NULL, NULL }
 };
 
+/**
+ * @enum_name@_build_string_from_mask:
+ * @mask: bitmask of @EnumName@ values.
+ *
+ * Builds a string containing a comma-separated list of nicknames for
+ * each #@EnumName@ in @mask.
+ *
+ * Returns: (transfer full): a string with the list of nicknames, or %NULL if none given. The returned value should be freed with g_free().
+ */
 gchar *
 @enum_name@_build_string_from_mask (@EnumName@ mask)
 {