[glib] g_file_new_for_commandline_arg: clarify encoding

[Ryan Lortie <desrt src gnome org>]

commit 643f2b348dea7486ef2eaa4f8e4eb858bce5f3e1
Author: Ryan Lortie <desrt desrt ca>
Date:   Thu Jan 16 22:11:18 2014 -0500

    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

 gio/gfile.c |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)
---
diff --git a/gio/gfile.c b/gio/gfile.c
index a832e91..e319510 100644
--- 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().
  */