From 51fc82a567be04f43300c0f226b90452501b1f9d Mon Sep 17 00:00:00 2001
From: velsinki <112010-velsinki@users.noreply.gitlab.gnome.org>
Date: Tue, 9 Jan 2024 00:37:26 +0100
Subject: [PATCH] gstrfuncs: Improve and port g_set_str() docs to gi-docgen

Fixes link and code block and includes code syntax.

Improves documentation to be more in line with the developer guidelines.
---
 glib/gstrfuncs.h | 38 ++++++++++++++++++++++----------------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/glib/gstrfuncs.h b/glib/gstrfuncs.h
index cb021b658..19ba95c5d 100644
--- a/glib/gstrfuncs.h
+++ b/glib/gstrfuncs.h
@@ -456,28 +456,34 @@ gboolean              g_ascii_string_to_unsigned   (const gchar  *str,
 
 /**
  * g_set_str: (skip)
- * @str_pointer: (inout) (not optional) (nullable): a pointer to either a string or %NULL
- * @new_str: (nullable): a string to assign to @str_pointer, or %NULL
+ * @str_pointer: (inout) (not optional) (nullable): a pointer to either
+ *   a string or `NULL`
+ * @new_str: (nullable): a string to assign to @str_pointer
  *
- * Updates a pointer to a string to a copy of @new_str. The previous string
- * pointed to by @str_pointer will be freed with g_free().
+ * Updates a pointer to a string to a copy of @new_str and returns whether the
+ * string was changed.
  *
- * @str_pointer must not be %NULL, but can point to a %NULL value.
+ * If @new_str matches the previous string, this function is a no-op. If
+ * @new_str is different, a copy of it will be assigned to @str_pointer and
+ * the previous string pointed to by @str_pointer will be freed with
+ * [func@GLib.free].
+ *
+ * @str_pointer must not be `NULL`, but can point to a `NULL` value.
  *
  * One convenient usage of this function is in implementing property settings:
- * |[
- *   void
- *   foo_set_bar (Foo        *foo,
- *                const char *new_bar)
- *   {
- *     g_return_if_fail (IS_FOO (foo));
+ * ```C
+ * void
+ * foo_set_bar (Foo        *foo,
+ *              const char *new_bar)
+ * {
+ *   g_return_if_fail (IS_FOO (foo));
  *
- *     if (g_set_str (&foo->bar, new_bar))
- *       g_object_notify (foo, "bar");
- *   }
- * ]|
+ *   if (g_set_str (&foo->bar, new_bar))
+ *     g_object_notify (foo, "bar");
+ * }
+ * ```
  *
- * Returns: %TRUE if the value of @str_pointer changed, %FALSE otherwise
+ * Returns: true if the value of @str_pointer changed, false otherwise
  *
  * Since: 2.76
  */