Add documentation for the gio.FileInfo class

The docs for this class are not completed, missing methods descriptions.
The index is complete though, it will be completed once all the classes
are in place so we can ship a (almost) complete reference.

2 files changed, 347 insertions, 0 deletions

diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml
index 58c3994..e4f2b53 100644
--- a/docs/reference/pygio-classes.xml
+++ b/docs/reference/pygio-classes.xml
@@ -18,6 +18,7 @@
 <xi:include href="pygio-fileattributeinfo.xml"/>
 <xi:include href="pygio-fileenumerator.xml"/>
 <xi:include href="pygio-fileicon.xml"/>
+<xi:include href="pygio-fileinfo.xml"/>
 <xi:include href="pygio-icon.xml"/>
 <xi:include href="pygio-inputstream.xml"/>
 <xi:include href="pygio-loadableicon.xml"/>
diff --git a/docs/reference/pygio-fileinfo.xml b/docs/reference/pygio-fileinfo.xml
new file mode 100644
index 0000000..33eeae7
--- /dev/null
+++ b/docs/reference/pygio-fileinfo.xml
@@ -0,0 +1,346 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<refentry id="class-giofileinfo">
+    <refnamediv>
+        <refname>gio.FileInfo</refname>
+        <refpurpose>File Information and Attributes</refpurpose>
+    </refnamediv>
+
+    <refsect1>
+        <title>Synopsis</title>
+
+    <classsynopsis language="python">
+        <ooclass><classname>gio.FileInfo</classname></ooclass>
+        <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass>
+    
+    <constructorsynopsis language="python">
+    <methodname><link linkend="constructor-giofileinfo">gio.FileInfo</link></methodname>
+        <methodparam></methodparam>
+    </constructorsynopsis>
+
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--clear-status">clear_status</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--copy-into">copy_into</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--dup">dup</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-as-string">get_attribute_as_string</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-boolean">get_attribute_boolean</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-byte-string">get_attribute_byte_string</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-data">get_attribute_data</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-int32">get_attribute_int32</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-int64">get_attribute_int64</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-object">get_attribute_object</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-status">get_attribute_status</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-string">get_attribute_string</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-type">get_attribute_type</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-uint32">get_attribute_uint32</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-attribute-uint64">get_attribute_uint64</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-content-type">get_content_type</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-display-name">get_display_name</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-edit-name">get_edit_name</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-etag">get_etag</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-file-type">get_file_type</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-icon">get_icon</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-is-backup">get_is_backup</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-is-hidden">get_is_hidden</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-is-symlink">get_is_symlink</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-modification-time">get_modification_time</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-name">get_name</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-size">get_size</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-sort-order">get_sort_order</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--get-symlink-target">get_symlink_target</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--has-attribute">has_attribute</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--list-attributes">list_attributes</link></methodname>
+        <methodparam><parameter role="keyword">name_space</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--remove-attribute">remove_attribute</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute">set_attribute</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+        <methodparam><parameter role="keyword">type</parameter></methodparam>
+        <methodparam><parameter role="keyword">value_p</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute-boolean">set_attribute_boolean</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+        <methodparam><parameter role="keyword">attr_value</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute-byte-string">set_attribute_byte_string</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+        <methodparam><parameter role="keyword">attr_value</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute-data">set_attribute_data</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+        <methodparam><parameter role="keyword">attr_value</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute-int32">set_attribute_int32</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+        <methodparam><parameter role="keyword">attr_value</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute-int64">set_attribute_int64</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+        <methodparam><parameter role="keyword">attr_value</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute-int64">set_attribute_mask</link></methodname>
+        <methodparam><parameter role="keyword">mask</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute-object">set_attribute_object</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+        <methodparam><parameter role="keyword">attr_value</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute-status">set_attribute_status</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+        <methodparam><parameter role="keyword">attr_value</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute-string">set_attribute_string</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+        <methodparam><parameter role="keyword">attr_value</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute-uint32">set_attribute_uint32</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-attribute-uint64">set_attribute_uint64</link></methodname>
+        <methodparam><parameter role="keyword">attribute</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-content-type">set_content_type</link></methodname>
+        <methodparam><parameter role="keyword">content_type</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-display-name">set_display_name</link></methodname>
+        <methodparam><parameter role="keyword">display_name</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-edit-name">set_edit_name</link></methodname>
+        <methodparam><parameter role="keyword">edit_name</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-file-type">set_file_type</link></methodname>
+        <methodparam><parameter role="keyword">type</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-icon">set_icon</link></methodname>
+        <methodparam><parameter role="keyword">icon</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-is-hidden">set_is_hidden</link></methodname>
+        <methodparam><parameter role="keyword">is_hidden</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-is-symlink">set_is_symlink</link></methodname>
+        <methodparam><parameter role="keyword">is_symlink</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-modification-time">set_modification_time</link></methodname>
+        <methodparam><parameter role="keyword">mtime</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-name">set_name</link></methodname>
+        <methodparam><parameter role="keyword">name</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-size">set_size</link></methodname>
+        <methodparam><parameter role="keyword">size</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-sort-order">set_sort_order</link></methodname>
+        <methodparam><parameter role="keyword">sort_order</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--set-symlink-tarset">set_symlink_tarset</link></methodname>
+        <methodparam><parameter role="keyword">symlink_target</parameter></methodparam>
+    </methodsynopsis>
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-giofileinfo--unset-attribute-mask">unset_attribute_mask</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+
+    </classsynopsis>
+
+    </refsect1>
+
+    <refsect1>
+        <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link>
+  +-- <link linkend="class-giofileinfo">gio.FileInfo</link>
+</synopsis>
+
+    </refsect1>
+
+    <refsect1>
+        <title>Description</title>
+
+        <para>
+            Functionality for manipulating basic metadata for files.
+            <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
+            implements methods for getting information that all files should contain,
+            and allows for manipulation of extended attributes.
+        </para>
+        <para>
+            See <link linkend="class-giofileattribute"><classname>gio.FileAttribute</classname></link>
+            for more information on how GIO handles file attributes.
+        </para>
+        <para>
+           To obtain a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
+           for a <link linkend="class-giofile"><classname>gio.File</classname></link>, use
+           <methodname><link linkend="method-giofile--query-info">gio.File.query_info</link></methodname>()
+           (or its async variant). To obtain a
+           <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
+           for a file input or output stream, use
+           <methodname><link linkend="method-giofileinputstream--query-info">gio.FileInputStream.query_info</link></methodname>() or
+           <methodname><link linkend="method-giofileoutputstream--query-info">gio.FileOutputStream.query_info</link></methodname>()
+           (or their async variants).
+        </para>
+        <para>
+           To change the actual attributes of a file, you should then set the attribute in the
+           <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> and call
+           <methodname><link linkend="method-giofile--set-attributes-from-info">gio.File.set_attributes_from_info</link></methodname>() or
+           <methodname><link linkend="method-giofile--set-attributes-async">gio.File.set_attributes_async</link></methodname>()
+           on a <link linkend="class-giofile"><classname>gio.File</classname></link>.
+        </para>
+        <para>
+           However, not all attributes can be changed in the file. For instance, the
+           actual size of a file cannot be changed via
+           <methodname><link linkend="method-giofileinfo--set-size">gio.FileInfo.set_size</link></methodname>(). You may call
+           <methodname><link linkend="method-giofile--query-settable-attributes">gio.File.query_settable_attributes</link></methodname>() and
+           <methodname><link linkend="method-giofile--query-writable-namespace">gio.File.query_writable_namespace</link></methodname>()
+           to discover the settable attributes of a particular file at runtime.
+        </para>
+        <para>
+           <link linkend="class-giofileattributematcher"><classname>gio.FileAttributeMatcher</classname></link>
+           allows for searching through a GFileInfo for attributes.
+        </para>
+    </refsect1>
+
+    <refsect1 id="constructor-giofileinfo">
+        <title>Constructor</title>
+  
+        <programlisting><constructorsynopsis language="python">
+            <methodname>gio.FileInfo</methodname>
+            <methodparam></methodparam>
+        </constructorsynopsis></programlisting>
+        <variablelist>
+            <varlistentry>
+                <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                <listitem><simpara>a new
+                <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
+                </simpara></listitem>
+            </varlistentry>
+        </variablelist>
+    
+        <para>
+            Creates a new <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
+        </para>
+  
+    </refsect1>
+
+    <refsect1>
+        <title>Methods</title>
+        <para> Unfinished section, you may want to see the relevant C API docs for methods descriptions.</para>
+    </refsect1>
+</refentry>