docs: include documentation for enum/flags helpers

2 files changed, 30 insertions, 20 deletions

diff --git a/build-aux/mm-enums-template.c b/build-aux/mm-enums-template.c
index 7f12c2c59..15f3a8137 100644
--- a/build-aux/mm-enums-template.c
+++ b/build-aux/mm-enums-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 __MM_IS_ENUM__
+#undef __MM_IS_FLAGS__
+#define __MM_IS_@TYPE@__
 
 GType
 @enum_name@_get_type (void)
@@ -36,10 +36,15 @@ GType
     return g_define_type_id__volatile;
 }
 
-/* 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
+/**
+ * @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.
+ */
+#if defined __MM_IS_ENUM__
 const gchar *
 @enum_name@_get_string (@EnumName@ val)
 {
@@ -52,13 +57,18 @@ const gchar *
 
     return NULL;
 }
-#endif /* 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
+#endif /* __MM_IS_ENUM_ */
+
+/**
+ * @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().
+ */
+#if defined __MM_IS_FLAGS__
 gchar *
 @enum_name@_build_string_from_mask (@EnumName@ mask)
 {
@@ -96,7 +106,7 @@ gchar *
 
     return (str ? g_string_free (str, FALSE) : NULL);
 }
-#endif /* IS_FLAGS */
+#endif /* __MM_IS_FLAGS__ */
 
 /*** END value-tail ***/
 
diff --git a/build-aux/mm-enums-template.h b/build-aux/mm-enums-template.h
index 13db2a6d8..652c53dcb 100644
--- a/build-aux/mm-enums-template.h
+++ b/build-aux/mm-enums-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 __MM_IS_ENUM__
+#undef __MM_IS_FLAGS__
+#define __MM_IS_@TYPE@__
 
-#if defined IS_ENUM
+#if defined __MM_IS_ENUM__
 const gchar *@enum_name@_get_string (@EnumName@ val);
 #endif
 
-#if defined IS_FLAGS
+#if defined __MM_IS_FLAGS__
 gchar *@enum_name@_build_string_from_mask (@EnumName@ mask);
 #endif