g_file_new_for_commandline_arg: clarify encoding

Add a note to the documentation for g_file_new_for_commandline_arg()
that this function is intended to operate on strings already in the GLib
filename encoding on Windows.

This has been the case for a long time, but this documents the
requirement.

https://bugzilla.gnome.org/show_bug.cgi?id=722025

diff --git a/gio/gfile.c b/gio/gfile.c
index a832e91..e319510 100644 (file)
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -6462,6 +6462,15 @@ new_for_cmdline_arg (const gchar *arg,
  * This operation never fails, but the returned object might not
  * support any I/O operation if @arg points to a malformed path.
  *
+ * Note that on Windows, this function expects its argument to be in
+ * UTF-8 -- not the system code page.  This means that you
+ * should not use this function with string from argv as it is passed
+ * to main().  g_win32_get_command_line() will return a UTF-8 version of
+ * the commandline.  #GApplication also uses UTF-8 but
+ * g_application_command_line_create_file_for_arg() may be more useful
+ * for you there.  It is also always possible to use this function with
+ * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
+ *
  * Returns: (transfer full): a new #GFile.
  *    Free the returned object with g_object_unref().
  */