From 2ff0f64ce13bda99e15bc78986ffd3778a09fdef Mon Sep 17 00:00:00 2001 From: Christophe Fergeau Date: Tue, 29 Jul 2008 20:10:39 +0000 Subject: Add gtk-doc documentation git-svn-id: https://gtkpod.svn.sf.net/svnroot/gtkpod/libgpod/trunk@2068 f01d2545-417e-4e96-918e-98f8d0dbbcb6 --- ChangeLog | 5 +++ src/itdb_plist.c | 24 ++++++++++++ src/itdb_sysinfo_extended_parser.c | 80 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 109 insertions(+) diff --git a/ChangeLog b/ChangeLog index 08ba91f..a2cb790 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2008-07-27 Christophe Fergeau + + * src/itdb_sysinfo_extended_parser.c: + * src/itdb_plist.c: add gtk-doc documentation + 2008-07-27 Christophe Fergeau * src/itdb_sysinfo_extended_parser.c: diff --git a/src/itdb_plist.c b/src/itdb_plist.c index 6efdc48..41d21b9 100644 --- a/src/itdb_plist.c +++ b/src/itdb_plist.c @@ -311,6 +311,17 @@ itdb_plist_parse (xmlNode * a_node, GError **error) return NULL; } +/** + * itdb_plist_parse: + * @filename: name of the XML plist file to parse + * @error: return location for a #GError + * + * Returns: NULL on error (@error will be set), a newly allocated GValue + * containing a GHashTable otherwise. + * + * Parses the XML plist file stored in @filename. If an error occurs during + * the parsing, itdb_plist_parse will return NULL and @error will be set + **/ GValue * itdb_plist_parse_from_file (const char *filename, GError **error) { @@ -336,6 +347,19 @@ itdb_plist_parse_from_file (const char *filename, GError **error) return parsed_doc; } +/** + * itdb_plist_parse_from_memory: + * @data: memory location containing XML plist data to parse + * @len: length in bytes of the string to parse + * @error: return location for a #GError + * + * Returns: NULL on error (@error will be set), a newly allocated GValue + * containing a GHashTable otherwise. + * + * Parses the XML plist file stored in @data which length is @len bytes. If + * an error occurs during the parsing, itdb_plist_parse_from_memory will + * return NULL and @error will be set + **/ GValue * itdb_plist_parse_from_memory (const char *data, gsize len, GError **error) { diff --git a/src/itdb_sysinfo_extended_parser.c b/src/itdb_sysinfo_extended_parser.c index 18b194a..a402eef 100644 --- a/src/itdb_sysinfo_extended_parser.c +++ b/src/itdb_sysinfo_extended_parser.c @@ -501,6 +501,18 @@ static SysInfoIpodProperties *g_value_to_ipod_properties (GValue *value) return props; } +/** + * 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 + * + * 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 + **/ SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename, GError **error) { @@ -520,6 +532,22 @@ SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename, return props; } +/** + * 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 + * http://svn.gnome.org/viewvc/podsleuth/trunk/src/PodSleuth/PodSleuth/SerialNumber.cs?view=markup + * for more details about what the various parts of the serial number + * 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 :) + **/ const char * itdb_sysinfo_properties_get_serial_number (const SysInfoIpodProperties *props) { @@ -527,6 +555,20 @@ itdb_sysinfo_properties_get_serial_number (const SysInfoIpodProperties *props) return props->serial_number; } +/** + * 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. + **/ const char * itdb_sysinfo_properties_get_firewire_id (const SysInfoIpodProperties *props) { @@ -534,6 +576,15 @@ itdb_sysinfo_properties_get_firewire_id (const SysInfoIpodProperties *props) return props->firewire_guid; } +/** + * 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 + * modified nor freed. + * + **/ const GList * itdb_sysinfo_properties_get_cover_art_formats (const SysInfoIpodProperties *props) { @@ -541,6 +592,15 @@ itdb_sysinfo_properties_get_cover_art_formats (const SysInfoIpodProperties *prop return props->artwork_formats; } +/** + * 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 + * modified nor freed. + * + **/ const GList * itdb_sysinfo_properties_get_photo_formats (const SysInfoIpodProperties *props) { @@ -548,6 +608,15 @@ itdb_sysinfo_properties_get_photo_formats (const SysInfoIpodProperties *props) return props->photo_formats; } +/** + * 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 + * not be modified nor freed. + * + **/ const GList * itdb_sysinfo_properties_get_chapter_image_formats (const SysInfoIpodProperties *props) { @@ -555,6 +624,17 @@ itdb_sysinfo_properties_get_chapter_image_formats (const SysInfoIpodProperties * return props->chapter_image_formats; } +/** + * 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. + **/ G_GNUC_INTERNAL gboolean itdb_sysinfo_properties_supports_sparse_artwork (const SysInfoIpodProperties *props) { -- cgit