changeset 2057:a55ad33d882e trunk

[svn] - document rcfile
author nenolod
date Mon, 04 Dec 2006 18:08:15 -0800
parents 6f1346ce2764
children 2618fcfb3bcf
files ChangeLog doc/libaudacious/libaudacious-undocumented.txt doc/libaudacious/tmpl/rcfile.sgml libaudacious/rcfile.c
diffstat 4 files changed, 161 insertions(+), 25 deletions(-) [+]
line wrap: on
line diff
--- a/ChangeLog	Mon Dec 04 15:24:14 2006 -0800
+++ b/ChangeLog	Mon Dec 04 18:08:15 2006 -0800
@@ -1,3 +1,13 @@
+2006-12-04 23:24:14 +0000  William Pitcock <nenolod@nenolod.net>
+  revision [3115]
+  - document xconvert
+  
+  trunk/doc/libaudacious/libaudacious-undocumented.txt |    7 -
+  trunk/doc/libaudacious/tmpl/xconvert.sgml            |    4 
+  trunk/libaudacious/xconvert.c                        |   77 ++++++++++++++++++-
+  3 files changed, 79 insertions(+), 9 deletions(-)
+
+
 2006-12-04 23:03:22 +0000  William Pitcock <nenolod@nenolod.net>
   revision [3113]
   - cleanups from oliver@freebsd.org
--- a/doc/libaudacious/libaudacious-undocumented.txt	Mon Dec 04 15:24:14 2006 -0800
+++ b/doc/libaudacious/libaudacious-undocumented.txt	Mon Dec 04 18:08:15 2006 -0800
@@ -1,7 +1,7 @@
-71% symbol docs coverage.
-111 symbols documented.
+82% symbol docs coverage.
+128 symbols documented.
 7 symbols incomplete.
-46 not documented.
+29 not documented.
 
 
 BmpTitleInput
@@ -16,21 +16,6 @@
 XMMS_NEW_TITLEINPUT
 XMMS_TITLEINPUT_SIZE
 XMMS_TITLEINPUT_VERSION
-bmp_rcfile_free
-bmp_rcfile_new
-bmp_rcfile_open
-bmp_rcfile_read_bool
-bmp_rcfile_read_double
-bmp_rcfile_read_float
-bmp_rcfile_read_int
-bmp_rcfile_read_string
-bmp_rcfile_remove_key
-bmp_rcfile_write
-bmp_rcfile_write_boolean
-bmp_rcfile_write_double
-bmp_rcfile_write_float
-bmp_rcfile_write_int
-bmp_rcfile_write_string
 convert_free_buffer
 vfs_fgets
 vfs_fprintf
@@ -54,8 +39,6 @@
 dirbrowser:Short_Description
 formatter:Long_Description
 rcfile:Long_Description
-rcfile:Short_Description
 titlestring:Long_Description
 util:Long_Description
 xconvert:Long_Description
-xconvert:Short_Description
--- a/doc/libaudacious/tmpl/rcfile.sgml	Mon Dec 04 15:24:14 2006 -0800
+++ b/doc/libaudacious/tmpl/rcfile.sgml	Mon Dec 04 18:08:15 2006 -0800
@@ -1,8 +1,8 @@
 <!-- ##### SECTION Title ##### -->
-rcfile
+RcFile
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Manipulation of RcFiles (old XMMS ConfigFile)
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
--- a/libaudacious/rcfile.c	Mon Dec 04 15:24:14 2006 -0800
+++ b/libaudacious/rcfile.c	Mon Dec 04 18:08:15 2006 -0800
@@ -1,4 +1,10 @@
-/*  This program is free software; you can redistribute it and/or modify
+/*  Audacious
+ *  Copyright (c) 2005-2007  Audacious team
+ *
+ *  BMP
+ *  Copyright (c) 2003-2005  BMP team
+ *
+ *  This program is free software; you can redistribute it and/or modify
  *  it under the terms of the GNU General Public License as published by
  *  the Free Software Foundation; either version 2 of the License, or
  *  (at your option) any later version.
@@ -32,13 +38,25 @@
 static RcSection *bmp_rcfile_find_section(RcFile * file, const gchar * name);
 static RcLine *bmp_rcfile_find_string(RcSection * section, const gchar * key);
 
-
+/**
+ * bmp_rcfile_new:
+ *
+ * #RcFile object factory.
+ *
+ * Return value: A #RcFile object.
+ **/
 RcFile *
 bmp_rcfile_new(void)
 {
     return g_new0(RcFile, 1);
 }
 
+/**
+ * bmp_rcfile_free:
+ * @file: A #RcFile object to destroy.
+ *
+ * #RcFile object destructor.
+ **/
 void
 bmp_rcfile_free(RcFile * file)
 {
@@ -71,6 +89,14 @@
     g_free(file);
 }
 
+/**
+ * bmp_rcfile_open:
+ * @filename: Path to rcfile to open.
+ *
+ * Opens an rcfile and returns an #RcFile object representing it.
+ *
+ * Return value: An #RcFile object representing the rcfile given.
+ **/
 RcFile *
 bmp_rcfile_open(const gchar * filename)
 {
@@ -86,7 +112,7 @@
     if (!g_file_get_contents(filename, &buffer, NULL, NULL))
         return NULL;
 
-    file = g_malloc0(sizeof(RcFile));
+    file = bmp_rcfile_new();
     lines = g_strsplit(buffer, "\n", 0);
     g_free(buffer);
     i = 0;
@@ -113,6 +139,15 @@
     return file;
 }
 
+/**
+ * bmp_rcfile_write:
+ * @file: A #RcFile object to write to disk.
+ * @filename: A path to write the #RcFile object's data to.
+ *
+ * Writes the contents of a #RcFile object to disk.
+ *
+ * Return value: TRUE on success, FALSE otherwise.
+ **/
 gboolean
 bmp_rcfile_write(RcFile * file, const gchar * filename)
 {
@@ -146,6 +181,17 @@
     return TRUE;
 }
 
+/**
+ * bmp_rcfile_read_string:
+ * @file: A #RcFile object to write to disk.
+ * @section: The section of the RcFile to look in.
+ * @key: The name of the identifier to look up.
+ * @value: A pointer to a memory location to place the data.
+ *
+ * Looks up a value in an RcFile and places it in %value.
+ *
+ * Return value: TRUE on success, FALSE otherwise.
+ **/
 gboolean
 bmp_rcfile_read_string(RcFile * file, const gchar * section,
                        const gchar * key, gchar ** value)
@@ -166,6 +212,17 @@
     return TRUE;
 }
 
+/**
+ * bmp_rcfile_read_int:
+ * @file: A #RcFile object to write to disk.
+ * @section: The section of the RcFile to look in.
+ * @key: The name of the identifier to look up.
+ * @value: A pointer to a memory location to place the data.
+ *
+ * Looks up a value in an RcFile and places it in %value.
+ *
+ * Return value: TRUE on success, FALSE otherwise.
+ **/
 gboolean
 bmp_rcfile_read_int(RcFile * file, const gchar * section,
                     const gchar * key, gint * value)
@@ -185,6 +242,17 @@
     return TRUE;
 }
 
+/**
+ * bmp_rcfile_read_bool:
+ * @file: A #RcFile object to write to disk.
+ * @section: The section of the RcFile to look in.
+ * @key: The name of the identifier to look up.
+ * @value: A pointer to a memory location to place the data.
+ *
+ * Looks up a value in an RcFile and places it in %value.
+ *
+ * Return value: TRUE on success, FALSE otherwise.
+ **/
 gboolean
 bmp_rcfile_read_bool(RcFile * file, const gchar * section,
                      const gchar * key, gboolean * value)
@@ -206,6 +274,17 @@
     return TRUE;
 }
 
+/**
+ * bmp_rcfile_read_float:
+ * @file: A #RcFile object to write to disk.
+ * @section: The section of the RcFile to look in.
+ * @key: The name of the identifier to look up.
+ * @value: A pointer to a memory location to place the data.
+ *
+ * Looks up a value in an RcFile and places it in %value.
+ *
+ * Return value: TRUE on success, FALSE otherwise.
+ **/
 gboolean
 bmp_rcfile_read_float(RcFile * file, const gchar * section,
                       const gchar * key, gfloat * value)
@@ -230,6 +309,17 @@
     return TRUE;
 }
 
+/**
+ * bmp_rcfile_read_double:
+ * @file: A #RcFile object to write to disk.
+ * @section: The section of the RcFile to look in.
+ * @key: The name of the identifier to look up.
+ * @value: A pointer to a memory location to place the data.
+ *
+ * Looks up a value in an RcFile and places it in %value.
+ *
+ * Return value: TRUE on success, FALSE otherwise.
+ **/
 gboolean
 bmp_rcfile_read_double(RcFile * file, const gchar * section,
                        const gchar * key, gdouble * value)
@@ -254,6 +344,15 @@
     return TRUE;
 }
 
+/**
+ * bmp_rcfile_write_string:
+ * @file: A #RcFile object to write to disk.
+ * @section: The section of the RcFile to set the key in.
+ * @key: The name of the identifier to set.
+ * @value: The value to set for that identifier.
+ *
+ * Sets a value in an RcFile for %key.
+ **/
 void
 bmp_rcfile_write_string(RcFile * file, const gchar * section,
                         const gchar * key, const gchar * value)
@@ -277,6 +376,15 @@
         bmp_rcfile_create_string(sect, key, value);
 }
 
+/**
+ * bmp_rcfile_write_int:
+ * @file: A #RcFile object to write to disk.
+ * @section: The section of the RcFile to set the key in.
+ * @key: The name of the identifier to set.
+ * @value: The value to set for that identifier.
+ *
+ * Sets a value in an RcFile for %key.
+ **/
 void
 bmp_rcfile_write_int(RcFile * file, const gchar * section,
                      const gchar * key, gint value)
@@ -292,6 +400,15 @@
     g_free(strvalue);
 }
 
+/**
+ * bmp_rcfile_write_boolean:
+ * @file: A #RcFile object to write to disk.
+ * @section: The section of the RcFile to set the key in.
+ * @key: The name of the identifier to set.
+ * @value: The value to set for that identifier.
+ *
+ * Sets a value in an RcFile for %key.
+ **/
 void
 bmp_rcfile_write_boolean(RcFile * file, const gchar * section,
                          const gchar * key, gboolean value)
@@ -306,6 +423,15 @@
         bmp_rcfile_write_string(file, section, key, "FALSE");
 }
 
+/**
+ * bmp_rcfile_write_float:
+ * @file: A #RcFile object to write to disk.
+ * @section: The section of the RcFile to set the key in.
+ * @key: The name of the identifier to set.
+ * @value: The value to set for that identifier.
+ *
+ * Sets a value in an RcFile for %key.
+ **/
 void
 bmp_rcfile_write_float(RcFile * file, const gchar * section,
                        const gchar * key, gfloat value)
@@ -325,6 +451,15 @@
     g_free(strvalue);
 }
 
+/**
+ * bmp_rcfile_write_double:
+ * @file: A #RcFile object to write to disk.
+ * @section: The section of the RcFile to set the key in.
+ * @key: The name of the identifier to set.
+ * @value: The value to set for that identifier.
+ *
+ * Sets a value in an RcFile for %key.
+ **/
 void
 bmp_rcfile_write_double(RcFile * file, const gchar * section,
                         const gchar * key, gdouble value)
@@ -344,6 +479,14 @@
     g_free(strvalue);
 }
 
+/**
+ * bmp_rcfile_remove_key:
+ * @file: A #RcFile object to write to disk.
+ * @section: The section of the RcFile to set the key in.
+ * @key: The name of the identifier to remove.
+ *
+ * Removes %key from an #RcFile object.
+ **/
 void
 bmp_rcfile_remove_key(RcFile * file, const gchar * section, const gchar * key)
 {