- * Creates a reference to a file by opening a file chooser dialog. If @fmode is
- * #filemode_Read, then the file must already exist and the user will be asked
- * to select from existing files. If @fmode is #filemode_Write, then the file
- * should not exist; if the user selects an existing file, he or she will be
- * warned that it will be replaced. If @fmode is #filemode_ReadWrite, then the
- * file may or may not exist; if it already exists, the user will be warned
- * that it will be modified. The @fmode argument should generally match the
- * @fmode which will be used to open the file.
+ * Creates a reference to a file by asking the player to locate it. The library
+ * may simply prompt the player to type a name, or may use a platform-native
+ * file navigation tool. (The prompt, if any, is inferred from the usage
+ * argument.)
+ *
+ * <note><title>Chimara</title>
+ * <para>
+ * Chimara uses a <link
+ * linkend="gtk-GtkFileChooserDialog">GtkFileChooserDialog</link>.
+ * </para></note>
+ *
+ * @fmode must be one of these values:
+ * <variablelist>
+ * <varlistentry>
+ * <term>#filemode_Read</term>
+ * <listitem><para>The file must already exist; and the player will be asked
+ * to select from existing files which match the usage.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>#filemode_Write</term>
+ * <listitem><para>The file should not exist; if the player selects an
+ * existing file, he will be warned that it will be replaced.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>#filemode_ReadWrite</term>
+ * <listitem><para>The file may or may not exist; if it already exists, the
+ * player will be warned that it will be modified.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>#filemode_WriteAppend</term>
+ * <listitem><para>Same behavior as #filemode_ReadWrite.</para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ *
+ * The @fmode argument should generally match the @fmode which will be used to
+ * open the file.
+ *
+ * <note><para>
+ * It is possible that the prompt or file tool will have a
+ * <quote>cancel</quote> option. If the player chooses this,
+ * glk_fileref_create_by_prompt() will return %NULL. This is a major reason
+ * why you should make sure the return value is valid before you use it.
+ * </para></note>