diff --git a/src/utils.c b/src/utils.c
index 7980d148..7dd66a46 100644
--- a/src/utils.c
+++ b/src/utils.c
@@ -217,15 +217,19 @@ gboolean utils_is_opening_brace(gchar c, gboolean include_angles)
 
 
 /**
- *  Writes the given @a text into a file with @a filename.
- *  If the file doesn't exist, it will be created.
- *  If it already exists, it will be overwritten.
+ * Writes @a text into a file named @a filename.
+ * If the file doesn't exist, it will be created.
+ * If it already exists, it will be overwritten.
  *
- *  @param filename The filename of the file to write, in locale encoding.
- *  @param text The text to write into the file.
+ * @warning You should use @c g_file_set_contents() instead if you don't need
+ * file permissions and other metadata to be preserved, as that always handles
+ * disk exhaustion safely.
  *
- *  @return 0 if the file was successfully written, otherwise the @c errno of the
- *          failed operation is returned.
+ * @param filename The filename of the file to write, in locale encoding.
+ * @param text The text to write into the file.
+ *
+ * @return 0 if the file was successfully written, otherwise the @c errno of the
+ *         failed operation is returned.
  **/
 gint utils_write_file(const gchar *filename, const gchar *text)
 {