Add docs for etags

svn path=/trunk/; revision=6001

9 files changed, 50 insertions, 31 deletions

diff --git a/gio/ChangeLog b/gio/ChangeLog
index 006e23c16..eab929921 100644
--- a/gio/ChangeLog
+++ b/gio/ChangeLog
@@ -1,3 +1,7 @@
+2007-11-30  Matthias Clasen <mclasen@redhat.com>
+
+	* *.c: Explain etags and link to the explanation
+
 2007-11-29  Matthias Clasen <mclasen@redhat.com>
 
 	* *.c: Explain I/O priority.
diff --git a/gio/gbufferedinputstream.c b/gio/gbufferedinputstream.c
index a3994a8aa..62c96f986 100644
--- a/gio/gbufferedinputstream.c
+++ b/gio/gbufferedinputstream.c
@@ -445,7 +445,7 @@ async_fill_callback_wrapper (GObject      *source_object,
  * g_buffered_input_stream_fill_async:
  * @stream: #GBufferedInputStream.
  * @count: a #gssize.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request.
  * @cancellable: optional #GCancellable object
  * @callback: a #GAsyncReadyCallback.
diff --git a/gio/gfile.c b/gio/gfile.c
index 9c1d381b6..6ff826c02 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -46,7 +46,8 @@
  * virtual file system. #GFile<!-- -->s are lightweight, immutable 
  * objects that do no I/O upon creation. It is necessary to understand that
  * #GFile objects do not represent files, merely a handle to a file. All
- * file I/O is implemented as streaming operations (see #GInputStream and #GOutputStream).
+ * file I/O is implemented as streaming operations (see #GInputStream and 
+ * #GOutputStream).
  * 
  * To construct a #GFile, you can use: 
  * g_file_new_for_path() if you have a path.
@@ -72,7 +73,14 @@
  * g_file_unmount_mountable() to unmount a mountable file.
  * g_file_eject_mountable() to eject a mountable file.
  * 
- *
+ * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
+ * One notable feature of #GFile<!-- -->s are entity tags, or "etags" for 
+ * short. Entity tags are somewhat like a more abstract version of the 
+ * traditional mtime, and can be used to quickly determine if the file has
+ * been modified from the version on the file system. See the HTTP 1.1 
+ * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19">specification</ulink>
+ * for HTTP Etag headers, which are a very similar concept.
+ * </para>
  **/
 
 static void g_file_base_init (gpointer g_class);
@@ -669,7 +677,7 @@ g_file_enumerate_children (GFile                *file,
  * @file: input #GFile.
  * @attributes: a string containing a #GFileAttributeInfo query.
  * @flags: a set of #GFileQueryInfoFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
@@ -797,7 +805,7 @@ g_file_query_info (GFile                *file,
  * @file: input #GFile.
  * @attributes: a string containing a #GFileAttributeInfo query.
  * @flags: a set of #GFileQueryInfoFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
@@ -1095,8 +1103,9 @@ g_file_create (GFile             *file,
 /**
  * g_file_replace:
  * @file: input #GFile.
- * @etag: an Entity Tag for the current #GFile.
- * @make_backup: %TRUE if a backup should be created.
+ * @etag: an <link linkend="gfile-etag">entity tag</link> for the 
+ *     current #GFile.
+ * @make_backup: %TRUE if a backup should be created`.
  * @flags: a set of #GFileCreateFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError, or %NULL
@@ -1154,7 +1163,7 @@ g_file_replace (GFile             *file,
 /**
  * g_file_read_async:
  * @file: input #GFile.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback.
@@ -1227,7 +1236,7 @@ g_file_read_finish (GFile         *file,
  * g_file_append_to_async:
  * @file: input #GFile.
  * @flags: a set of #GFileCreateFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback. 
@@ -1304,7 +1313,7 @@ g_file_append_to_finish (GFile         *file,
  * g_file_create_async:
  * @file: input #GFile.
  * @flags: a set of #GFileCreateFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback. 
@@ -1380,10 +1389,11 @@ g_file_create_finish (GFile         *file,
 /**
  * g_file_replace_async:
  * @file: input #GFile.
- * @etag: an Entity Tag for the current #GFile.
+ * @etag: an <link linkend="gfile-etag">entity tag</link> for the 
+ *     current #GFile.
  * @make_backup: a #gboolean.
  * @flags: a set of #GFileCreateFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback. 
@@ -2299,7 +2309,7 @@ g_file_set_display_name (GFile         *file,
  * g_file_set_display_name_async:
  * @file: input #GFile.
  * @display_name: a string.
- * @io_priority: the <link linkend="gioscheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback. 
@@ -2611,7 +2621,7 @@ g_file_real_set_attributes_from_info (GFile                *file,
  * @file: input #GFile.
  * @info: a #GFileInfo.
  * @flags: a #GFileQueryInfoFlags.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback. 
@@ -4390,10 +4400,12 @@ g_file_load_contents_finish (GFile         *file,
  * @file: input #GFile.
  * @contents: a string containing the new contents for @file.
  * @length: the length of @contents in bytes.
- * @etag: the old entity tag for the document.
+ * @etag: the old <link linkend="gfile-etag">entity tag</link> 
+ *     for the document.
  * @make_backup: a #gboolean.
  * @flags: a set of #GFileCreateFlags.
- * @new_etag: a location to a new entity tag for the document.
+ * @new_etag: a location to a new <link linkend="gfile-etag">entity tag</link>
+ *      for the document.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError, or %NULL
  *
@@ -4592,7 +4604,7 @@ replace_contents_open_callback (GObject      *obj,
  * @file: input #GFile.
  * @contents: string of contents to replace the file with.
  * @length: the length of @contents in bytes.
- * @etag: a new entity tag for the @file.
+ * @etag: a new <link linkend="gfile-etag">entity tag</link> for the @file.
  * @make_backup: a #gboolean.
  * @flags: a set of #GFileCreateFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
@@ -4655,7 +4667,8 @@ g_file_replace_contents_async  (GFile               *file,
  * g_file_replace_contents_finish:
  * @file: input #GFile.
  * @res: a #GAsyncResult. 
- * @new_etag: a location of a new entity tag for the document.
+ * @new_etag: a location of a new <link linkend="gfile-etag">entity tag</link> 
+ *     for the document.
  * @error: a #GError, or %NULL 
  * 
  * Finishes an asynchronous replace of the given @file. See
diff --git a/gio/gfileattribute.c b/gio/gfileattribute.c
index d11b25bfb..facdf3820 100644
--- a/gio/gfileattribute.c
+++ b/gio/gfileattribute.c
@@ -67,14 +67,14 @@
  * </thead>
  * <tbody>
  * <row><entry>"std"</entry><entry>The "Standard" namespace. General file
- * information that any application may need should be put in this namespace. Examples
- * include the file's name, type, and size.</entry></row> 
+ * information that any application may need should be put in this namespace. 
+ * Examples include the file's name, type, and size.</entry></row> 
  * <row><entry>"etag"</entry><entry>The "Entity Tag" namespace. 
  * GIO use "entity tags" to quickly determine if a file has been modified
- * from the version on the file system. Entity tags are globally unique identifiers, 
- * and should always be sent with the current revision of a file. 
- * An example of a key in this namespace is "value", which contains the value of the 
- * current entity tag.</entry></row>
+ * from the version on the file system. Entity tags are globally unique 
+ * identifiers, and should always be sent with the current revision of a 
+ * file. An example of a key in this namespace is "value", which contains 
+ * the value of the current entity tag.</entry></row>
  * <row><entry>"id"</entry><entry>The "Identification" namespace. This 
  * namespace is used by file managers and applications that list directories
  * to check for loops and to uniquely identify files.</entry></row>
diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c
index de4c38caa..e525aa8a1 100644
--- a/gio/gfileenumerator.c
+++ b/gio/gfileenumerator.c
@@ -363,7 +363,7 @@ close_async_callback_wrapper (GObject      *source_object,
 /**
  * g_file_enumerator_close_async:
  * @enumerator: a #GFileEnumerator.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @callback: callback to call when the request is satisfied
diff --git a/gio/gfileinfo.c b/gio/gfileinfo.c
index 3ce611d9c..4c574b580 100644
--- a/gio/gfileinfo.c
+++ b/gio/gfileinfo.c
@@ -1325,8 +1325,8 @@ g_file_info_get_symlink_target (GFileInfo *info)
  * g_file_info_get_etag:
  * @info: a #GFileInfo.
  * 
- * Gets the entity tag for a given #GFileInfo. 
- * See %G_FILE_ATTRIBUTE_ETAG_VALUE.
+ * Gets the <link linkend="gfile-etag">entity tag</link> for a given 
+ * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
  * 
  * Returns: a string containing the value of the "etag:value" attribute.
  **/
diff --git a/gio/gfileinputstream.c b/gio/gfileinputstream.c
index c7dd4cfdd..57056dba9 100644
--- a/gio/gfileinputstream.c
+++ b/gio/gfileinputstream.c
@@ -181,7 +181,7 @@ async_ready_callback_wrapper (GObject      *source_object,
  * g_file_input_stream_query_info_async:
  * @stream: a #GFileInputStream.
  * @attributes: a file attribute query string.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @callback: callback to call when the request is satisfied
diff --git a/gio/ginputstream.c b/gio/ginputstream.c
index afc82a27c..548691b99 100644
--- a/gio/ginputstream.c
+++ b/gio/ginputstream.c
@@ -520,7 +520,7 @@ async_ready_close_callback_wrapper (GObject      *source_object,
  * @stream: A #GInputStream.
  * @buffer: a buffer to read data into (which should be at least count bytes long).
  * @count: the number of bytes that will be read from the stream
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  * of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: callback to call when the request is satisfied
@@ -655,7 +655,7 @@ g_input_stream_read_finish (GInputStream  *stream,
  * g_input_stream_skip_async:
  * @stream: A #GInputStream.
  * @count: the number of bytes that will be skipped from the stream
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  * of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @callback: callback to call when the request is satisfied
@@ -787,7 +787,7 @@ g_input_stream_skip_finish (GInputStream  *stream,
 /**
  * g_input_stream_close_async:
  * @stream: A #GInputStream.
- * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> 
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  * of the request. 
  * @cancellable: optional cancellable object
  * @callback: callback to call when the request is satisfied
diff --git a/gio/gioscheduler.c b/gio/gioscheduler.c
index 52e2ca626..13a8cf477 100644
--- a/gio/gioscheduler.c
+++ b/gio/gioscheduler.c
@@ -33,12 +33,14 @@
  * Schedules asynchronous I/O operations for integration into the main 
  * event loop (#GMainLoop).
  * 
+ * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm>
  * Each I/O operation has a priority, and the scheduler uses the priorities
  * to determine the order in which operations are executed. They are 
  * <emphasis>not</emphasis> used to determine system-wide I/O scheduling.
  * Priorities are integers, with lower numbers indicating higher priority. 
  * It is recommended to choose priorities between %G_PRIORITY_LOW and 
  * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default.
+ * </para>
  **/
 
 struct _GIOJob {