# HG changeset patch # User nenolod # Date 1165219802 28800 # Node ID c43fb0845b716cd068e41bc5c493b2a701b12383 # Parent 34299070db299f3ad5ff48ac9a0e63da20f6da02 [svn] - update VFS documentation - include gtkdoc templates for libaudacious diff -r 34299070db29 -r c43fb0845b71 ChangeLog --- a/ChangeLog Sun Dec 03 23:26:42 2006 -0800 +++ b/ChangeLog Mon Dec 04 00:10:02 2006 -0800 @@ -1,3 +1,11 @@ +2006-12-04 07:26:42 +0000 William Pitcock + revision [3069] + - make documentation-build will invoke gtk-doc to compile the audacious SDK docs. + + trunk/Makefile | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ + 1 file changed, 48 insertions(+) + + 2006-12-04 06:35:18 +0000 William Pitcock revision [3067] - document the VFS layer. diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/beepctrl.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libaudacious/tmpl/beepctrl.sgml Mon Dec 04 00:10:02 2006 -0800 @@ -0,0 +1,648 @@ + +beepctrl + + + + + + + + + + + + + + + + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@list: +@num: +@enqueue: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@list: + + + + + + + +@session: +@pos: + + + + + + + +@session: + + + + + + + +@session: + + + + + + + +@session: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@pos: + + + + + + + +@session: +@Returns: + + + + + + + +@session: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@pos: + + + + + + + +@session: +@vl: +@vr: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@vl: +@vr: + + + + + + + +@session: +@v: + + + + + + + +@session: +@b: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@skinfile: + + + + + + + +@session: +@pos: +@Returns: + + + + + + + +@session: +@pos: +@Returns: + + + + + + + +@session: +@pos: +@Returns: + + + + + + + +@session: +@rate: +@freq: +@nch: + + + + + + + +@session: +@show: + + + + + + + +@session: +@show: + + + + + + + +@session: +@show: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@Returns: + + + + + + + +@session: + + + + + + + +@session: +@ontop: + + + + + + + +@session: + + + + + + + +@session: + + + + + + + +@session: + + + + + + + +@session: +@string: + + + + + + + +@session: +@Returns: + + + + + + + +@session: + + + + + + + +@session: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@preamp: +@bands: + + + + + + + +@session: +@Returns: + + + + + + + +@session: +@band: +@Returns: + + + + + + + +@session: +@preamp: +@bands: + + + + + + + +@session: +@preamp: + + + + + + + +@session: +@band: +@value: + + + + + + + +@session: + + + + + + + +@session: + + + + + + + +@session: +@string: +@pos: + + + + + + + +@session: +@pos: + + + + + + + +@session: +@pos: + + + + + + + +@session: +@Returns: + + + + + + + +@session: + + + + + + + +@session: +@Returns: + + + + + + + +@session: + + + + + + + +@session: + + + + + + + +@session: + + + + + + + +@session: +@pos: +@Returns: + + + + + + + +@session: +@pos: +@Returns: + + + + + + + +@session: +@pos: +@Returns: + + + + + + + +@uri: + + + + + + + +@session: +@Returns: + + + + + + + +@type: + + + + + + + +@session: +@list: + + + + + + + +@session: +@list: + + diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/configdb.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libaudacious/tmpl/configdb.sgml Mon Dec 04 00:10:02 2006 -0800 @@ -0,0 +1,166 @@ + +configdb + + + + + + + + + + + + + + + + + + + + + + + + + + + + +@Returns: + + + + + + + +@db: + + + + + + + +@db: +@section: +@key: +@value: +@Returns: + + + + + + + +@db: +@section: +@key: +@value: +@Returns: + + + + + + + +@db: +@section: +@key: +@value: +@Returns: + + + + + + + +@db: +@section: +@key: +@value: +@Returns: + + + + + + + +@db: +@section: +@key: +@value: +@Returns: + + + + + + + +@db: +@section: +@key: +@value: + + + + + + + +@db: +@section: +@key: +@value: + + + + + + + +@db: +@section: +@key: +@value: + + + + + + + +@db: +@section: +@key: +@value: + + + + + + + +@db: +@section: +@key: +@value: + + + + + + + +@db: +@section: +@key: + + diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/dirbrowser.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libaudacious/tmpl/dirbrowser.sgml Mon Dec 04 00:10:02 2006 -0800 @@ -0,0 +1,31 @@ + +dirbrowser + + + + + + + + + + + + + + + + + + + + + + +@title: +@current_path: +@mode: +@handler: +@Returns: + + diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/formatter.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libaudacious/tmpl/formatter.sgml Mon Dec 04 00:10:02 2006 -0800 @@ -0,0 +1,71 @@ + +formatter + + + + + + + + + + + + + + + + + + + + + + +@values: + + + + + + +@Returns: + + + + + + + +@formatter: + + + + + + + +@formatter: +@id: +@value: + + + + + + + +@formatter: +@id: + + + + + + + +@formatter: +@format: +@Returns: + + diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/libaudacious-unused.sgml diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/rcfile.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libaudacious/tmpl/rcfile.sgml Mon Dec 04 00:10:02 2006 -0800 @@ -0,0 +1,202 @@ + +rcfile + + + + + + + + + + + + + + + + + + + + + + +@key: +@value: + + + + + + +@name: +@lines: + + + + + + +@sections: + + + + + + +@Returns: + + + + + + + +@file: + + + + + + + +@filename: +@Returns: + + + + + + + +@file: +@filename: +@Returns: + + + + + + + +@file: +@section: +@key: +@value: +@Returns: + + + + + + + +@file: +@section: +@key: +@value: +@Returns: + + + + + + + +@file: +@section: +@key: +@value: +@Returns: + + + + + + + +@file: +@section: +@key: +@value: +@Returns: + + + + + + + +@file: +@section: +@key: +@value: +@Returns: + + + + + + + +@file: +@section: +@key: +@value: + + + + + + + +@file: +@section: +@key: +@value: + + + + + + + +@file: +@section: +@key: +@value: + + + + + + + +@file: +@section: +@key: +@value: + + + + + + + +@file: +@section: +@key: +@value: + + + + + + + +@file: +@section: +@key: + + diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/titlestring.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libaudacious/tmpl/titlestring.sgml Mon Dec 04 00:10:02 2006 -0800 @@ -0,0 +1,105 @@ + +titlestring + + + + + + + + + + + + + + + + + + + + + + +@__size: +@__version: +@performer: +@album_name: +@track_name: +@track_number: +@year: +@date: +@genre: +@comment: +@file_name: +@file_ext: +@file_path: +@length: +@formatter: +@mtime: + + + + + + + + + + + + + + + + + + + + + + + + + + +@input: + + + + + + + +@Returns: + + + + + + + +@input: + + + + + + + +@fmt: +@input: +@Returns: + + + + + + + +@tags: +@rows: +@Returns: + + diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/util.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libaudacious/tmpl/util.sgml Mon Dec 04 00:10:02 2006 -0800 @@ -0,0 +1,19 @@ + +util + + + + + + + + + + + + + + + + + diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/vfs.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libaudacious/tmpl/vfs.sgml Mon Dec 04 00:10:02 2006 -0800 @@ -0,0 +1,213 @@ + +VFS + + +Stream-based I/O in Audacious + + + +Audacious uses the VFS subsystem for moving implementing types of streams. + + + + + + + + + + + + + + + +@uri: +@handle: +@base: + + + + + + +@uri_id: +@vfs_fopen_impl: +@vfs_fclose_impl: +@vfs_fread_impl: +@vfs_fwrite_impl: +@vfs_getc_impl: +@vfs_ungetc_impl: +@vfs_fseek_impl: +@vfs_rewind_impl: +@vfs_ftell_impl: +@vfs_feof_impl: +@vfs_truncate_impl: + + + + + + +@Returns: + + + + + + + +@path: +@mode: +@Returns: + + + + + + + +@file: +@Returns: + + + + + + + +@ptr: +@size: +@nmemb: +@file: +@Returns: + + + + + + + +@ptr: +@size: +@nmemb: +@file: +@Returns: + + + + + + + +@stream: +@Returns: + + + + + + + +@c: +@stream: +@Returns: + + + + + + + +@s: +@n: +@stream: +@Returns: + + + + + + + +@file: +@offset: +@whence: +@Returns: + + + + + + + +@file: + + + + + + + +@file: +@Returns: + + + + + + + +@file: +@Returns: + + + + + + + +@path: +@test: +@Returns: + + + + + + + +@path: +@Returns: + + + + + + + +@file: +@length: +@Returns: + + + + + + + +@stream: +@format: +@Varargs: +@Returns: + + + + + + + +@vtable: +@Returns: + + diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/xconvert.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libaudacious/tmpl/xconvert.sgml Mon Dec 04 00:10:02 2006 -0800 @@ -0,0 +1,32 @@ + +xconvert + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/xentry.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libaudacious/tmpl/xentry.sgml Mon Dec 04 00:10:02 2006 -0800 @@ -0,0 +1,34 @@ + +XmmsEntry + + + + + + + + + + + + + + + + + + + + + + +@entry: + + + + + + +@Returns: + + diff -r 34299070db29 -r c43fb0845b71 doc/libaudacious/tmpl/xml_document.sgml --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/libaudacious/tmpl/xml_document.sgml Mon Dec 04 00:10:02 2006 -0800 @@ -0,0 +1,224 @@ + +xml_document + + + + + + + + + + + + + + + + + + + + + + +@BMP_XML_NODE_DOC: +@BMP_XML_NODE_ELEMENT: +@BMP_XML_NODE_ATTRIB: +@BMP_XML_NODE_TEXT: + + + + + + +@x: + + + + + + + +@tree: +@current_node: +@current_depth: +@parse_context: + + + + + + +@x: + + + + + + + +@type: + + + + + + +@x: + + + + + + + +@type: + + + + + + +@x: + + + + + + + +@type: +@name: + + + + + + +@x: + + + + + + + +@type: +@name: +@value: + + + + + + +@x: + + + + + + + +@type: +@text: +@length: + + + + + + +@Returns: + + + + + + + +@data: + + + + + + + +@name: +@Returns: + + + + + + + +@data: + + + + + + + +@name: +@value: +@Returns: + + + + + + + +@data: + + + + + + + +@data: + + + + + + + +@text: +@length: +@Returns: + + + + + + + +@document: +@filename: +@error: +@Returns: + + + + + + + +@document: + + + + + + + +@document: +@Returns: + + diff -r 34299070db29 -r c43fb0845b71 libaudacious/vfs.c --- 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) {