diff libaudacious/vfs.c @ 2034:c43fb0845b71 trunk

[svn] - update VFS documentation - include gtkdoc templates for libaudacious

--- a/libaudacious/vfs.c	Sun Dec 03 23:26:42 2006 -0800
+++ b/libaudacious/vfs.c	Mon Dec 04 00:10:02 2006 -0800
@@ -31,20 +31,14 @@
 # define DBG(x, args...)
 #endif
 
-/*
- * vfs_register_transport(VFSConstructor *vtable)
- *
- * Registers a VFSConstructor vtable with the VFS system.
+/**
+ * vfs_register_transport:
+ * @vtable: The #VFSConstructor vtable to register.
  *
- * Inputs:
- *     - a VFSConstructor object
+ * Registers a #VFSConstructor vtable with the VFS system.
  *
- * Outputs:
- *     - TRUE on success, FALSE on failure.
- *
- * Side Effects:
- *     - none
- */
+ * Return value: TRUE on success, FALSE on failure.
+ **/
 gboolean
 vfs_register_transport(VFSConstructor *vtable)
 {
@@ -53,22 +47,15 @@
     return TRUE;
 }
 
-/*
- * vfs_fopen(const gchar * path, const gchar * mode)
- *
- * Opens a stream from a VFS transport using a VFSConstructor.
+/**
+ * vfs_fopen:
+ * @path: The path or URI to open.
+ * @mode: The preferred access privileges (not guaranteed).
  *
- * Inputs:
- *     - path or URI to open
- *     - preferred access privileges (not guaranteed)
+ * Opens a stream from a VFS transport using a #VFSConstructor.
  *
- * Outputs:
- *     - on success, a VFSFile object representing the VFS stream
- *     - on failure, nothing
- *
- * Side Effects:
- *     - file descriptors are opened or more memory is allocated.
- */
+ * Return value: On success, a #VFSFile object representing the stream.
+ **/
 VFSFile *
 vfs_fopen(const gchar * path,
           const gchar * mode)
@@ -128,20 +115,14 @@
     return file;
 }
 
-/*
- * vfs_fclose(VFSFile * file)
- *
- * Closes a VFS stream and destroys a VFSFile object.
+/**
+ * vfs_fclose:
+ * @file: A #VFSFile object to destroy.
  *
- * Inputs:
- *     - a VFSFile object to destroy
+ * Closes a VFS stream and destroys a #VFSFile object.
  *
- * Outputs:
- *     - -1 on success, otherwise 0
- *
- * Side Effects:
- *     - a file description is closed or allocated memory is freed
- */
+ * Return value: -1 on failure, 0 on success.
+ **/
 gint
 vfs_fclose(VFSFile * file)
 {
@@ -161,25 +142,17 @@
     return ret;
 }
 
-/*
- * vfs_fread(gpointer ptr, size_t size, size_t nmemb, VFSFile * file)
+/**
+ * vfs_fread:
+ * @ptr: A pointer to the destination buffer.
+ * @size: The size of each element to read.
+ * @nmemb: The number of elements to read.
+ * @file: #VFSFile object that represents the VFS stream.
  *
  * Reads from a VFS stream.
  *
- * Inputs:
- *     - pointer to destination buffer
- *     - size of each element to read
- *     - number of elements to read
- *     - VFSFile object that represents the VFS stream
- *
- * Outputs:
- *     - on success, the amount of elements successfully read
- *     - on failure, -1
- *
- * Side Effects:
- *     - on nonblocking sources, the socket may be unavailable after 
- *       this call.
- */
+ * Return value: The amount of elements succesfully read.
+ **/
 size_t
 vfs_fread(gpointer ptr,
           size_t size,
@@ -192,25 +165,17 @@
     return file->base->vfs_fread_impl(ptr, size, nmemb, file);
 }
 
-/*
- * vfs_fwrite(gconstpointer ptr, size_t size, size_t nmemb, VFSFile * file)
+/**
+ * vfs_fwrite:
+ * @ptr: A const pointer to the source buffer.
+ * @size: The size of each element to write.
+ * @nmemb: The number of elements to write.
+ * @file: #VFSFile object that represents the VFS stream.
  *
  * Writes to a VFS stream.
  *
- * Inputs:
- *     - const pointer to source buffer
- *     - size of each element to write
- *     - number of elements to write
- *     - VFSFile object that represents the VFS stream
- *
- * Outputs:
- *     - on success, the amount of elements successfully written
- *     - on failure, -1
- *
- * Side Effects:
- *     - on nonblocking sources, the socket may be unavailable after 
- *       this call.
- */
+ * Return value: The amount of elements succesfully written.
+ **/
 size_t
 vfs_fwrite(gconstpointer ptr,
            size_t size,
@@ -223,22 +188,14 @@
     return file->base->vfs_fwrite_impl(ptr, size, nmemb, file);
 }
 
-/*
- * vfs_getc(VFSFile *stream)
+/**
+ * vfs_getc:
+ * @stream: #VFSFile object that represents the VFS stream.
  *
  * Reads a character from a VFS stream.
  *
- * Inputs:
- *     - a VFSFile object representing a VFS stream.
- *
- * Outputs:
- *     - on success, a character
- *     - on failure, -1
- *
- * Side Effects:
- *     - on nonblocking sources, the socket may be unavailable after 
- *       this call.
- */
+ * Return value: On success, a character. Otherwise, -1.
+ **/
 gint
 vfs_getc(VFSFile *stream)
 {
@@ -248,23 +205,14 @@
     return stream->base->vfs_getc_impl(stream);
 }
 
-/*
- * vfs_ungetc(gint c, VFSFile *stream)
+/**
+ * vfs_ungetc:
+ * @stream: #VFSFile object that represents the VFS stream.
  *
  * Pushes a character back to the VFS stream.
  *
- * Inputs:
- *     - a character to push back
- *     - a VFSFile object representing a VFS stream.
- *
- * Outputs:
- *     - on success, 0
- *     - on failure, -1
- *
- * Side Effects:
- *     - on nonblocking sources, the socket may be unavailable after 
- *       this call.
- */
+ * Return value: On success, 0. Otherwise, -1.
+ **/
 gint
 vfs_ungetc(gint c, VFSFile *stream)
 {
@@ -274,23 +222,16 @@
     return stream->base->vfs_ungetc_impl(c, stream);
 }
 
-/*
- * vfs_fseek(VFSFile * file, gint offset, gint whence)
+/**
+ * vfs_fseek:
+ * @file: #VFSFile object that represents the VFS stream.
+ * @offset: The offset to seek to.
+ * @whence: Whether or not the seek is absolute or not.
  *
  * Seeks through a VFS stream.
  *
- * Inputs:
- *     - a VFSFile object which represents a VFS stream
- *     - the offset to seek
- *     - whether or not the seek is absolute or non-absolute
- *
- * Outputs:
- *     - on success, 1
- *     - on failure, 0
- *
- * Side Effects:
- *     - on nonblocking sources, this is not guaranteed to work
- */
+ * Return value: On success, 1. Otherwise, 0.
+ **/
 gint
 vfs_fseek(VFSFile * file,
           glong offset,
@@ -302,20 +243,12 @@
     return file->base->vfs_fseek_impl(file, offset, whence);
 }
 
-/*
- * vfs_rewind(VFSFile * file)
+/**
+ * vfs_rewind:
+ * @file: #VFSFile object that represents the VFS stream.
  *
  * Rewinds a VFS stream.
- *
- * Inputs:
- *     - a VFSFile object which represents a VFS stream
- *
- * Outputs:
- *     - nothing
- *
- * Side Effects:
- *     - on nonblocking sources, this is not guaranteed to work
- */
+ **/
 void
 vfs_rewind(VFSFile * file)
 {
@@ -325,21 +258,14 @@
     file->base->vfs_rewind_impl(file);
 }
 
-/*
- * vfs_ftell(VFSFile * file)
- *
- * Returns the position of a VFS stream.
- *
- * Inputs:
- *     - a VFSFile object which represents a VFS stream
+/**
+ * vfs_fseek:
+ * @file: #VFSFile object that represents the VFS stream.
  *
- * Outputs:
- *     - on failure, -1.
- *     - on success, the stream's position
+ * Returns the current position in the VFS stream's buffer.
  *
- * Side Effects:
- *     - on nonblocking sources, this is not guaranteed to work
- */
+ * Return value: On success, the current position. Otherwise, -1.
+ **/
 glong
 vfs_ftell(VFSFile * file)
 {
@@ -349,21 +275,14 @@
     return file->base->vfs_ftell_impl(file);
 }
 
-/*
- * vfs_feof(VFSFile * file)
+/**
+ * vfs_feof:
+ * @file: #VFSFile object that represents the VFS stream.
  *
  * Returns whether or not the VFS stream has reached EOF.
  *
- * Inputs:
- *     - a VFSFile object which represents a VFS stream
- *
- * Outputs:
- *     - on failure, FALSE.
- *     - on success, whether or not the VFS stream is at EOF.
- *
- * Side Effects:
- *     - none
- */
+ * Return value: On success, whether or not the VFS stream is at EOF. Otherwise, FALSE.
+ **/
 gboolean
 vfs_feof(VFSFile * file)
 {
@@ -373,23 +292,15 @@
     return (gboolean) file->base->vfs_feof_impl(file);
 }
 
-/*
- * vfs_truncate(VFSFile * file, glong size)
+/**
+ * vfs_truncate:
+ * @file: #VFSFile object that represents the VFS stream.
+ * @size: The length to truncate at.
  *
  * Truncates a VFS stream to a certain size.
  *
- * Inputs:
- *     - a VFS stream to truncate
- *     - length to truncate at
- *
- * Outputs:
- *     - -1 on failure
- *     - 0 on success
- *
- * Side Effects:
- *     - this is not guaranteed to work on non-blocking
- *       sources
- */
+ * Return value: On success, 0. Otherwise, -1.
+ **/
 gint
 vfs_truncate(VFSFile * file, glong size)
 {
@@ -399,45 +310,29 @@
     return file->base->vfs_truncate_impl(file, size);
 }
 
-/*
- * vfs_file_test(const gchar * path, GFileTest test)
+/**
+ * vfs_file_test:
+ * @path: A path to test.
+ * @test: A GFileTest to run.
  *
  * Wrapper for g_file_test().
  *
- * Inputs:
- *     - a path to test
- *     - a GFileTest to run
- *
- * Outputs:
- *     - the result of g_file_test().
- *
- * Side Effects:
- *     - g_file_test() is called.
- */
+ * Return value: The result of g_file_test().
+ **/
 gboolean
 vfs_file_test(const gchar * path, GFileTest test)
 {
     return g_file_test(path, test);
 }
 
-/*
- * vfs_is_writable(const gchar * path)
+/**
+ * vfs_is_writable:
+ * @path: A path to test.
  *
  * Tests if a file is writable.
  *
- * Inputs:
- *     - a path to test
- *
- * Outputs:
- *     - FALSE if the file is not writable
- *     - TRUE if the file is writable
- *
- * Side Effects:
- *     - stat() is called.
- *
- * Bugs:
- *     - stat() is not considered part of stdio
- */
+ * Return value: TRUE if the file is writable, otherwise FALSE.
+ **/
 gboolean
 vfs_is_writeable(const gchar * path)
 {