Add warning for utils_write_file() that g_file_set_contents() is a better choice…

Add warning for utils_write_file() that g_file_set_contents() is a better choice because it handles disk exhaustion safely.


git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@5454 ea778897-0a13-0410-b9d1-a72fbfd435f5

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)
 {