Mercurial > audlegacy
changeset 2060:53a3d5db6b58 trunk
[svn] - finish documenting the libaudacious API
line wrap: on
line diff
--- a/ChangeLog Mon Dec 04 18:30:58 2006 -0800 +++ b/ChangeLog Mon Dec 04 19:24:14 2006 -0800 @@ -1,3 +1,13 @@ +2006-12-05 02:30:58 +0000 William Pitcock <nenolod@nenolod.net> + revision [3121] + - documentation fixups + + trunk/libaudacious/titlestring.h | 2 - + trunk/libaudacious/vfs.c | 14 +++++------ + trunk/libaudacious/vfs_common.c | 48 ++++++++++++++++++++++++++++++++++++++- + 3 files changed, 55 insertions(+), 9 deletions(-) + + 2006-12-05 02:21:39 +0000 William Pitcock <nenolod@nenolod.net> revision [3119] - a directory browser widget
--- a/doc/libaudacious/libaudacious-decl-list.txt Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/libaudacious-decl-list.txt Mon Dec 04 19:24:14 2006 -0800 @@ -2,7 +2,6 @@ <FILE>vfs</FILE> VFSFile VFSConstructor -vfs_init vfs_fopen vfs_fclose vfs_fread @@ -142,7 +141,6 @@ <SECTION> <FILE>xconvert</FILE> -convert_free_buffer xmms_convert_buffers </SECTION>
--- a/doc/libaudacious/libaudacious-decl.txt Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/libaudacious-decl.txt Mon Dec 04 19:24:14 2006 -0800 @@ -33,11 +33,6 @@ }; </STRUCT> <FUNCTION> -<NAME>vfs_init</NAME> -<RETURNS>gboolean </RETURNS> -void -</FUNCTION> -<FUNCTION> <NAME>vfs_fopen</NAME> <RETURNS>VFSFile *</RETURNS> const gchar * path,const gchar * mode @@ -503,11 +498,7 @@ </MACRO> <MACRO> <NAME>XMMS_NEW_TITLEINPUT</NAME> -#define XMMS_NEW_TITLEINPUT(input) G_STMT_START { \ - input = g_new0(TitleInput, 1); \ - input->__size = XMMS_TITLEINPUT_SIZE; \ - input->__version = XMMS_TITLEINPUT_VERSION; \ -} G_STMT_END +#define XMMS_NEW_TITLEINPUT(input) input = bmp_title_input_new(); </MACRO> <FUNCTION> <NAME>bmp_title_input_new</NAME> @@ -527,7 +518,7 @@ <FUNCTION> <NAME>xmms_titlestring_descriptions</NAME> <RETURNS>GtkWidget *</RETURNS> -gchar * tags, gint rows +gchar * tags, gint columns </FUNCTION> <STRUCT> <NAME>Formatter</NAME> @@ -655,11 +646,6 @@ <RETURNS>void </RETURNS> RcFile * file, const gchar * section,const gchar * key </FUNCTION> -<FUNCTION> -<NAME>convert_free_buffer</NAME> -<RETURNS>void </RETURNS> -void -</FUNCTION> <STRUCT> <NAME>xmms_convert_buffers</NAME> struct xmms_convert_buffers;
--- a/doc/libaudacious/libaudacious-sections.txt Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/libaudacious-sections.txt Mon Dec 04 19:24:14 2006 -0800 @@ -2,7 +2,6 @@ <FILE>vfs</FILE> VFSFile VFSConstructor -vfs_init vfs_fopen vfs_fclose vfs_fread @@ -142,7 +141,6 @@ <SECTION> <FILE>xconvert</FILE> -convert_free_buffer xmms_convert_buffers </SECTION>
--- a/doc/libaudacious/libaudacious-undocumented.txt Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/libaudacious-undocumented.txt Mon Dec 04 19:24:14 2006 -0800 @@ -1,44 +1,8 @@ -82% symbol docs coverage. -128 symbols documented. -7 symbols incomplete. -29 not documented. +100% symbol docs coverage. +155 symbols documented. +0 symbols incomplete. +0 not documented. -BmpTitleInput -ConfigDb -Formatter -RcFile -RcLine -RcSection -TitleInput -VFSConstructor -VFSFile -XMMS_NEW_TITLEINPUT -XMMS_TITLEINPUT_SIZE -XMMS_TITLEINPUT_VERSION -convert_free_buffer -vfs_fgets -vfs_fprintf -vfs_fseek (offset, whence) -vfs_ftell -vfs_init -vfs_is_writeable -vfs_truncate (length) -vfs_ungetc (c) -xmms_convert_buffers -xmms_create_dir_browser -xmms_formatter_new (Returns) -xmms_remote_add_files -xmms_remote_playqueue_add (pos) -xmms_remote_playqueue_remove (pos) -xmms_titlestring_descriptions (rows) -beepctrl:Long_Description -configdb:Long_Description -dirbrowser:Short_Description -formatter:Long_Description -rcfile:Long_Description -titlestring:Long_Description -util:Long_Description -xconvert:Long_Description
--- a/doc/libaudacious/tmpl/beepctrl.sgml Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/tmpl/beepctrl.sgml Mon Dec 04 19:24:14 2006 -0800 @@ -6,7 +6,7 @@ <!-- ##### SECTION Long_Description ##### --> <para> - +The control socket is used to remotely control audacious. </para> <!-- ##### SECTION See_Also ##### -->
--- a/doc/libaudacious/tmpl/configdb.sgml Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/tmpl/configdb.sgml Mon Dec 04 19:24:14 2006 -0800 @@ -6,7 +6,7 @@ <!-- ##### SECTION Long_Description ##### --> <para> - +The configuration database is used to store settings used by Audacious and it's plugins. </para> <!-- ##### SECTION See_Also ##### -->
--- a/doc/libaudacious/tmpl/formatter.sgml Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/tmpl/formatter.sgml Mon Dec 04 19:24:14 2006 -0800 @@ -6,7 +6,7 @@ <!-- ##### SECTION Long_Description ##### --> <para> - +The formatter class provides a simple id->value substitution method, which is useful for plugins to use. </para> <!-- ##### SECTION See_Also ##### -->
--- a/doc/libaudacious/tmpl/libaudacious-unused.sgml Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/tmpl/libaudacious-unused.sgml Mon Dec 04 19:24:14 2006 -0800 @@ -29,6 +29,19 @@ @entry: +<!-- ##### FUNCTION convert_free_buffer ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION vfs_init ##### --> +<para> + +</para> + +@Returns: + <!-- ##### FUNCTION xmms_entry_new ##### --> <para>
--- a/doc/libaudacious/tmpl/rcfile.sgml Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/tmpl/rcfile.sgml Mon Dec 04 19:24:14 2006 -0800 @@ -6,7 +6,7 @@ <!-- ##### SECTION Long_Description ##### --> <para> - +Audacious plugins use RcFiles to store additional configuration data which may not be suitable for storage in the configuration database. </para> <!-- ##### SECTION See_Also ##### -->
--- a/doc/libaudacious/tmpl/titlestring.sgml Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/tmpl/titlestring.sgml Mon Dec 04 19:24:14 2006 -0800 @@ -6,7 +6,7 @@ <!-- ##### SECTION Long_Description ##### --> <para> - +Audacious uses Tuples to generate titles and store information about media. </para> <!-- ##### SECTION See_Also ##### --> @@ -99,7 +99,7 @@ </para> @tags: -@rows: +@columns: @Returns:
--- a/doc/libaudacious/tmpl/util.sgml Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/tmpl/util.sgml Mon Dec 04 19:24:14 2006 -0800 @@ -6,7 +6,7 @@ <!-- ##### SECTION Long_Description ##### --> <para> - +These are miscillaneous utility functions used by plugins. </para> <!-- ##### SECTION See_Also ##### -->
--- a/doc/libaudacious/tmpl/vfs.sgml Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/tmpl/vfs.sgml Mon Dec 04 19:24:14 2006 -0800 @@ -6,7 +6,8 @@ <!-- ##### SECTION Long_Description ##### --> <para> -Audacious uses the VFS subsystem for moving implementing types of streams. +Audacious uses the VFS subsystem for implementing the I/O transport layer. VFSConstructors provide a base table for deriving streams from. Stream +methods may be derived from the base classes registered with the VFS subsystem via vfs_register_transport(). </para> <!-- ##### SECTION See_Also ##### --> @@ -44,14 +45,6 @@ @vfs_feof_impl: @vfs_truncate_impl: -<!-- ##### FUNCTION vfs_init ##### --> -<para> - -</para> - -@Returns: - - <!-- ##### FUNCTION vfs_fopen ##### --> <para>
--- a/doc/libaudacious/tmpl/xconvert.sgml Mon Dec 04 18:30:58 2006 -0800 +++ b/doc/libaudacious/tmpl/xconvert.sgml Mon Dec 04 19:24:14 2006 -0800 @@ -6,7 +6,7 @@ <!-- ##### SECTION Long_Description ##### --> <para> - +Audacious plugins use XConvert to resample, downmix, upmix, and byteswap audio. </para> <!-- ##### SECTION See_Also ##### --> @@ -17,13 +17,6 @@ <!-- ##### SECTION Stability_Level ##### --> -<!-- ##### FUNCTION convert_free_buffer ##### --> -<para> - -</para> - - - <!-- ##### STRUCT xmms_convert_buffers ##### --> <para>
--- a/libaudacious/beepctrl.c Mon Dec 04 18:30:58 2006 -0800 +++ b/libaudacious/beepctrl.c Mon Dec 04 19:24:14 2006 -0800 @@ -1375,6 +1375,7 @@ /** * xmms_remote_playqueue_add: * @session: Legacy XMMS-style session identifier. + * @pos: The playlist position to add to the queue. * * Tells audacious to add a playlist entry to the playqueue. **/ @@ -1387,6 +1388,7 @@ /** * xmms_remote_playqueue_remove: * @session: Legacy XMMS-style session identifier. + * @pos: The playlist position to remove from the queue. * * Tells audacious to remove a playlist entry from the playqueue. **/
--- a/libaudacious/beepctrl.h Mon Dec 04 18:30:58 2006 -0800 +++ b/libaudacious/beepctrl.h Mon Dec 04 19:24:14 2006 -0800 @@ -126,6 +126,13 @@ /* Deprecated APIs */ void xmms_remote_play_files(gint session, GList * list); +/** + * xmms_remote_add_files: + * @session: Legacy XMMS-style session identifier. + * @list: A GList of files to add. + * + * Tells audacious to add files to the playlist. + **/ #define xmms_remote_add_files(session,list) \ xmms_remote_playlist_add(session,list)
--- a/libaudacious/configdb.h Mon Dec 04 18:30:58 2006 -0800 +++ b/libaudacious/configdb.h Mon Dec 04 19:24:14 2006 -0800 @@ -3,7 +3,11 @@ #include <glib.h> - +/** + * ConfigDb: + * + * A configuration database handle, opened with bmp_cfg_db_open(). + **/ typedef struct _ConfigDb ConfigDb;
--- a/libaudacious/formatter.c Mon Dec 04 18:30:58 2006 -0800 +++ b/libaudacious/formatter.c Mon Dec 04 19:24:14 2006 -0800 @@ -33,6 +33,8 @@ * xmms_formatter_new: * * Factory for #Formatter objects. + * + * Return value: A #Formatter object. **/ Formatter * xmms_formatter_new(void)
--- a/libaudacious/formatter.h Mon Dec 04 18:30:58 2006 -0800 +++ b/libaudacious/formatter.h Mon Dec 04 19:24:14 2006 -0800 @@ -3,6 +3,12 @@ #include <glib.h> +/** + * Formatter: + * @values: The stack of values used for replacement. + * + * Formatter objects contain id->replacement mapping tables. + **/ typedef struct { gchar *values[256]; } Formatter;
--- a/libaudacious/rcfile.h Mon Dec 04 18:30:58 2006 -0800 +++ b/libaudacious/rcfile.h Mon Dec 04 19:24:14 2006 -0800 @@ -20,16 +20,36 @@ #include <glib.h> +/** + * RcLine: + * @key: A key for the key->value mapping. + * @value: A value for the key->value mapping. + * + * RcLine objects contain key->value mappings. + **/ typedef struct { gchar *key; gchar *value; } RcLine; +/** + * RcSection: + * @name: The name for the #RcSection. + * @lines: A list of key->value mappings for the #RcSection. + * + * RcSection objects contain collections of key->value mappings. + **/ typedef struct { gchar *name; GList *lines; } RcSection; +/** + * RcFile: + * @sections: A list of sections. + * + * An RcFile object contains a collection of key->value mappings organized by section. + **/ typedef struct { GList *sections; } RcFile;
--- a/libaudacious/titlestring.h Mon Dec 04 18:30:58 2006 -0800 +++ b/libaudacious/titlestring.h Mon Dec 04 19:24:14 2006 -0800 @@ -25,13 +25,30 @@ #include <unistd.h> #include <time.h> -/* - * Struct which is passed to xmms_get_titlestring(). An input struct - * is allocated and initialized with XMMS_NEW_TITLEINPUT(). Before +/** + * TitleInput: + * @__size: Private field which describes the version of the TitleInput. + * @__version: Private field which describes the version of the TitleInput. + * @performer: The performer of the media that the tuple is describing. + * @album_name: The name of the album that contains the media. + * @track_name: The title of the media. + * @track_number: The track number of the media. + * @year: The year the media was published. + * @date: The date the media was published. + * @genre: The genre of the media. + * @comment: Any comments attached to the media. + * @file_name: The filename which refers to the media. + * @file_ext: The file's extension. + * @file_path: The path that the media is in. + * @length: The length of the media. + * @formatter: The format string that should be used. + * @mtime: The last modified time of the file. + * + * Tuple which is passed to xmms_get_titlestring(). An input tuple + * is allocated and initialized with bmp_title_input_new(). Before * passing the struct to xmms_get_titlestring() it should be filled * with appropriate field values. - */ - + **/ typedef struct { gint __size; /* Set by bmp_title_input_new() */ gint __version; /* Ditto */ @@ -52,6 +69,11 @@ time_t mtime; } TitleInput; +/** + * BmpTitleInput: + * + * An alternate name for the #TitleInput object. + **/ typedef TitleInput BmpTitleInput; @@ -62,14 +84,27 @@ * the struct layout. */ +/** + * XMMS_TITLEINPUT_SIZE: + * + * The size of the TitleInput object compiled into the library. + **/ #define XMMS_TITLEINPUT_SIZE sizeof(TitleInput) + +/** + * XMMS_TITLEINPUT_VERSION: + * + * The version of the TitleInput object compiled into the library. + **/ #define XMMS_TITLEINPUT_VERSION (1) -#define XMMS_NEW_TITLEINPUT(input) G_STMT_START { \ - input = g_new0(TitleInput, 1); \ - input->__size = XMMS_TITLEINPUT_SIZE; \ - input->__version = XMMS_TITLEINPUT_VERSION; \ -} G_STMT_END +/** + * XMMS_NEW_TITLEINPUT: + * @input: A TitleInput to initialize. + * + * Initializes a TitleInput object. Included for XMMS compatibility. + **/ +#define XMMS_NEW_TITLEINPUT(input) input = bmp_title_input_new(); G_BEGIN_DECLS
--- a/libaudacious/vfs.c Mon Dec 04 18:30:58 2006 -0800 +++ b/libaudacious/vfs.c Mon Dec 04 19:24:14 2006 -0800 @@ -207,6 +207,7 @@ /** * vfs_ungetc: + * @c: The character to push back. * @stream: #VFSFile object that represents the VFS stream. * * Pushes a character back to the VFS stream.
--- a/libaudacious/vfs.h Mon Dec 04 18:30:58 2006 -0800 +++ b/libaudacious/vfs.h Mon Dec 04 19:24:14 2006 -0800 @@ -26,12 +26,39 @@ typedef struct _VFSFile VFSFile; typedef struct _VFSConstructor VFSConstructor; +/** + * VFSFile: + * @uri: The URI of the stream. + * @handle: Opaque data used by the transport plugins. + * @base: The base vtable used for VFS functions. + * + * #VFSFile objects describe a VFS stream. + **/ struct _VFSFile { gchar *uri; gpointer handle; VFSConstructor *base; }; +/** + * VFSConstructor: + * @uri_id: The uri identifier, e.g. "file" would handle "file://" streams. + * @vfs_fopen_impl: A function pointer which points to a fopen implementation. + * @vfs_fclose_impl: A function pointer which points to a fclose implementation. + * @vfs_fread_impl: A function pointer which points to a fread implementation. + * @vfs_fwrite_impl: A function pointer which points to a fwrite implementation. + * @vfs_getc_impl: A function pointer which points to a getc implementation. + * @vfs_ungetc_impl: A function pointer which points to an ungetc implementation. + * @vfs_fseek_impl: A function pointer which points to a fseek implementation. + * @vfs_rewind_impl: A function pointer which points to a rewind implementation. + * @vfs_ftell_impl: A function pointer which points to a ftell implementation. + * @vfs_feof_impl: A function pointer which points to a feof implementation. + * @vfs_truncate_impl: A function pointer which points to a ftruncate implementation. + * + * #VFSConstructor objects contain the base vtables used for extrapolating + * a VFS stream. #VFSConstructor objects should be considered %virtual in + * nature. VFS base vtables are registered via vfs_register_transport(). + **/ struct _VFSConstructor { gchar *uri_id; VFSFile *(*vfs_fopen_impl)(const gchar *path, @@ -52,9 +79,6 @@ G_BEGIN_DECLS -/* Reserved for private use by BMP */ -extern gboolean vfs_init(void); - extern VFSFile * vfs_fopen(const gchar * path, const gchar * mode); extern gint vfs_fclose(VFSFile * file);
--- a/libaudacious/vfs_common.c Mon Dec 04 18:30:58 2006 -0800 +++ b/libaudacious/vfs_common.c Mon Dec 04 19:24:14 2006 -0800 @@ -113,6 +113,7 @@ * vfs_fprintf: * @stream: A #VFSFile object representing the stream. * @format: A printf-style format string. + * @...: A list of args to use. * * Writes a formatted string to a VFS stream. *
--- a/libaudacious/xconvert.c Mon Dec 04 18:30:58 2006 -0800 +++ b/libaudacious/xconvert.c Mon Dec 04 19:24:14 2006 -0800 @@ -28,11 +28,28 @@ #define IS_BIG_ENDIAN (G_BYTE_ORDER==G_BIG_ENDIAN) +/** + * buffer: + * + * Contains data for conversion. + * + * @buffer: A pointer to the memory being used in the conversion process. + * @size: The size of the memory being referenced. + **/ struct buffer { void *buffer; int size; }; +/** + * xmms_convert_buffers: + * + * Stores data for conversion. + * + * @format_buffer: A buffer for converting formats. + * @stereo_buffer: A buffer for downmixing or upmixing. + * @freq_buffer: A buffer used for resampling. + **/ struct xmms_convert_buffers { struct buffer format_buffer, stereo_buffer, freq_buffer; };