Update API documentation

Add new functions and missing enums, macros, and structs to the proper
places in the documentation, remove old/unused functions, and clean up
various minor issues.

git-svn-id: https://gtkpod.svn.sf.net/svnroot/gtkpod/libgpod/trunk@2159 f01d2545-417e-4e96-918e-98f8d0dbbcb6

1 files changed, 30 insertions, 31 deletions

diff --git a/src/itdb_sysinfo_extended_parser.c b/src/itdb_sysinfo_extended_parser.c
index 5408c91..a373b8b 100644
--- a/src/itdb_sysinfo_extended_parser.c
+++ b/src/itdb_sysinfo_extended_parser.c
@@ -501,16 +501,18 @@ static SysInfoIpodProperties *g_value_to_ipod_properties (GValue *value)
 
 /**
  * itdb_sysinfo_extended_parse:
- * @filename: name of the SysInfoExtended file to parse
- * @error: return location for a #GError
- * Returns: a newly allocated #SysInfoIpodProperties which must be freed
- * after use, or NULL if an error occurred during the parsing
+ * @filename:   name of the SysInfoExtended file to parse
+ * @error:      return location for a #GError
  *
  * itdb_sysinfo_extended_parse() parses a SysInfoExtended file into a
  * #SysInfoIpodProperties structure. This structure contains a lot of
- * information about the iPod properties (artwork format supported, podcast 
- * capabilities, ...) which can be queried using the appropriate accessors
- **/
+ * information about the iPod properties (artwork format supported,
+ * podcast capabilities, ...) which can be queried using the
+ * appropriate accessors.
+ *
+ * Returns: a newly allocated #SysInfoIpodProperties which must be
+ * freed after use, or NULL if an error occurred during the parsing
+ */
 SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename,
                                                     GError **error)
 {
@@ -534,9 +536,6 @@ SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename,
  * itdb_sysinfo_properties_get_serial_number:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: the iPod serial number, NULL if the serial number wasn't set in
- * @props. The returned string must not be modified nor freed.
- *
  * Gets the iPod serial number from @props if it was found while parsing
  * @props. The serial number uniquely identify an ipod and it can be used
  * to determine when it was produced and its model/color, see
@@ -545,7 +544,10 @@ SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename,
  * correspond to. Please avoid parsing this serial number by yourself and
  * ask for additionnal API in libgpod if you find yourself needing to parse
  * that serial number :)
- **/
+ *
+ * Returns: the iPod serial number, NULL if the serial number wasn't set in
+ * @props. The returned string must not be modified nor freed.
+ */
 const char *
 itdb_sysinfo_properties_get_serial_number (const SysInfoIpodProperties *props)
 {
@@ -557,16 +559,16 @@ itdb_sysinfo_properties_get_serial_number (const SysInfoIpodProperties *props)
  * itdb_sysinfo_properties_get_firewire_id:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: the iPod firewire ID, NULL if the serial number wasn't set in
- * @props. The returned string must not be modified nor freed.
- *
  * Gets the iPod firewire ID from @props if it was found while parsing
  * @props. Contrary to what its name implies, the firewire ID is also set
  * on USB iPods and is especially important on iPod Classic and Nano Video
  * since this ID (which is unique on each iPod) is needed to generate the
  * checksum that is required to write a valid iPod database on these
  * models.
- **/
+ *
+ * Returns: the iPod firewire ID, NULL if the serial number wasn't set in
+ * @props. The returned string must not be modified nor freed.
+ */
 const char *
 itdb_sysinfo_properties_get_firewire_id (const SysInfoIpodProperties *props)
 {
@@ -578,11 +580,10 @@ itdb_sysinfo_properties_get_firewire_id (const SysInfoIpodProperties *props)
  * itdb_sysinfo_properties_get_cover_art_formats:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: a #GList of #Itdb_ArtworkFormat describing the cover art formats 
- * supported by the iPod described in @props. The returned list must not be 
+ * Returns: a #GList of #Itdb_ArtworkFormat describing the cover art formats
+ * supported by the iPod described in @props. The returned list must not be
  * modified nor freed.
- *
- **/
+ */
 const GList *
 itdb_sysinfo_properties_get_cover_art_formats (const SysInfoIpodProperties *props)
 {
@@ -594,11 +595,10 @@ itdb_sysinfo_properties_get_cover_art_formats (const SysInfoIpodProperties *prop
  * itdb_sysinfo_properties_get_photo_formats:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: a #GList of #Itdb_ArtworkFormat describing the photo formats 
- * supported by the iPod described in @props. The returned list must not be 
+ * Returns: a #GList of #Itdb_ArtworkFormat describing the photo formats
+ * supported by the iPod described in @props. The returned list must not be
  * modified nor freed.
- *
- **/
+ */
 const GList *
 itdb_sysinfo_properties_get_photo_formats (const SysInfoIpodProperties *props)
 {
@@ -610,11 +610,10 @@ itdb_sysinfo_properties_get_photo_formats (const SysInfoIpodProperties *props)
  * itdb_sysinfo_properties_get_chapter_image_formats:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: a #GList of #Itdb_ArtworkFormat describing the chapter image 
- * formats supported by the iPod described in @props. The returned list must 
+ * Returns: a #GList of #Itdb_ArtworkFormat describing the chapter image
+ * formats supported by the iPod described in @props. The returned list must
  * not be modified nor freed.
- *
- **/
+ */
 const GList *
 itdb_sysinfo_properties_get_chapter_image_formats (const SysInfoIpodProperties *props)
 {
@@ -626,13 +625,13 @@ itdb_sysinfo_properties_get_chapter_image_formats (const SysInfoIpodProperties *
  * itdb_sysinfo_properties_supports_sparse_artwork:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: TRUE if the iPod supports sparse artwork, FALSE if it does not
- * or if @props doesn't contain any information about sparse artwork
- *
  * Sparse artwork is a way to share artwork between different iPod tracks
  * which make things more efficient space-wise. This function can be used
  * to check if the more space-efficient artwork storage can be used.
- **/
+ *
+ * Returns: TRUE if the iPod supports sparse artwork, FALSE if it does not
+ * or if @props doesn't contain any information about sparse artwork
+ */
 G_GNUC_INTERNAL gboolean
 itdb_sysinfo_properties_supports_sparse_artwork (const SysInfoIpodProperties *props)
 {