[pygobject] Add documentation for the gio.FileInfo class

[Gian Mario Tagliaretti <gianmt src gnome org>]

commit 002915e5f458fec5a89766a54e8119a70a80caa7
Author: Gian Mario Tagliaretti <gianmt gnome org>
Date:   Tue May 12 20:37:24 2009 +0200

    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.
---
 docs/Makefile.am                  |    2 +
 docs/reference/pygio-classes.xml  |    1 +
 docs/reference/pygio-fileinfo.xml |  346 +++++++++++++++++++++++++++++++++++++
 3 files changed, 349 insertions(+), 0 deletions(-)

diff --git a/docs/Makefile.am b/docs/Makefile.am
index fb761fb..8da8476 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -27,6 +27,7 @@ HTML_FILES =					\
 	html/class-giofileattributeinfo.html	\
 	html/class-giofileenumerator.html	\
 	html/class-giofileicon.html		\
+	html/class-giofileinfo.html		\
 	html/class-gioicon.html			\
 	html/class-gioinputstream.html		\
 	html/class-gioloadableicon.html		\
@@ -75,6 +76,7 @@ XML_FILES = 					\
 	reference/pygio-fileattributeinfo.xml	\
 	reference/pygio-fileenumerator.xml	\
 	reference/pygio-fileicon.xml 		\
+	reference/pygio-fileinfo.xml 		\
 	reference/pygio-icon.xml		\
 	reference/pygio-inputstream.xml		\
 	reference/pygio-loadableicon.xml	\
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>