Commits

shuerhaaken committed dd7bdcc

more documentation

Comments (0)

Files changed (9)

+commit efed7663618a6b379a7abec6a70797a071558b75
+Author: Jörn Magens <shuerhaaken@googlemail.com>
+Date:   Wed Oct 23 10:48:44 2013 +0200
+
+    more ordering and extend C test
+
 commit 807e693de3a41d9323b3fc9026e08987e2e796ad
 Author: Jörn Magens <shuerhaaken@googlemail.com>
 Date:   Wed Oct 23 01:02:59 2013 +0200

bindings/c/taginfo_c.cc

 static List<char *> strings;
 static bool stringManagementEnabled = false;
 
+//! Enable string management for libtaginfo
 void taginfo_info_enable_string_management(BOOL management) {
     stringManagementEnabled = bool(management);
 }
 
+//! Clean up used strings
+//! To be used in case string management is used
 void taginfo_info_free_strings() {
     if(!stringManagementEnabled)
         return;
         free(*it);
     strings.clear();
 }
+//*****************/STRING MANAGEMENT****************************************************
 
 static char **string_list_to_c_array(const StringList &list, int *out_length) {
     if(list.isEmpty()) {
     }
     return list;
 }
-//*****************/STRING MANAGEMENT****************************************************
 
 
 //*****************FACTORY CREATION******************************************************
-TagInfo_Info * taginfo_info_factory_make(const char *filename) {
+/*!
+ * Creates a TagInfo_Info object based on \a filename.  TagInfo will try to guess the file
+ * type.
+ *
+ * \return NULL if the file type cannot be determined or the file cannot
+ * be opened. The returned object should be freed with taginfo_info_free() after usage
+ */
+TagInfo_Info * taginfo_info_create_tag_info(const char *filename) {
     return reinterpret_cast<TagInfo_Info *>(Info::create_tag_info(filename));
 }
 
 /*!
- * Creates a TagInfo file based on \a filename and TagInfo_MediaFileType
+ * Creates a TagInfo_Info object based on \a filename and TagInfo_MediaFileType
  *
  * \return NULL if the file type cannot be determined or the file cannot
  * be opened. The returned object should be freed with taginfo_info_free() after usage
  */
-TagInfo_Info * taginfo_info_factory_make_with_format(const char *filename,
+TagInfo_Info * taginfo_info_create_tag_info_with_format(const char *filename,
                                                      TagInfo_MediaFileType media_file_type) {
     return reinterpret_cast<TagInfo_Info *>(Info::create_tag_info_with_format(filename, 
                                                                               (MediaFileType)media_file_type)
     );
 }
 
-TagInfo_Info *taginfo_info_factory_make_from_mime(const char *filename, const char *mime_type) {
+/*!
+ * Creates a TagInfo_Info object based on \a filename and mimetype
+ *
+ * \return NULL if the file type cannot be determined or the file cannot
+ * be opened. The returned object should be freed with taginfo_info_free() after usage
+ */
+TagInfo_Info * taginfo_info_create_tag_info_from_mime(const char *filename, const char *mime_type) {
     return reinterpret_cast<TagInfo_Info *>(Info::create_tag_info_from_mime(filename, 
                                                                             mime_type)
     );
 
 
 //*****************GENERAL MEMORY MANAGEMENT*********************************************
+/*!
+ * Frees a TagInfo_Info object.
+ */
+//! \param info A TagInfo_Info object
 void taginfo_info_free(TagInfo_Info *info) {
     delete reinterpret_cast<Info *>(info);
 }
 
 
 //*****************TAG READ/WRITE API****************************************************
+//! Load the tag information from the media file to the TagInfo_Info object
+//! \param info A TagInfo_Info object
 BOOL taginfo_info_load(TagInfo_Info *info) {
     Info *i = reinterpret_cast<Info *>(info);
     return i->load();
 }
+//! Save the tag information from the TagInfo_Info object to the media file.
+//! \param info A TagInfo_Info object
 BOOL taginfo_info_save(TagInfo_Info *info) {
     Info *i = reinterpret_cast<Info *>(info);
     return i->save();
 }
 
+//! Get the artist tag of a media track.
+/*!
+\return The artist as char *. In case the string management is not enabled, the caller should free this string
+*/
+//! \param info A TagInfo_Info object
 char * taginfo_info_get_artist(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String artist = i->get_artist();
         strings.prepend(s);
     return s;
 }
+//! Set the artist tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param artist Artist as const char *.
+*/
 void taginfo_info_set_artist(TagInfo_Info *info, const char *artist) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_artist(String(artist, String::UTF8));
 }
 
+//! Get the original artist of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The original artist as char *. In case the string management is not enabled, the caller should free this string
+*/
 char * taginfo_info_get_original_artist (const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String artist = i->get_original_artist ();
         strings.prepend(s);
     return s;
 }
+//! Set the original artist of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param original_artist Original artist as const char *.
+*/
 void taginfo_info_set_original_artist (TagInfo_Info *info, const char *artist) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_original_artist (String(artist, String::UTF8));
 }
 
+//! Get the album of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The album as char *. In case the string management is not enabled, the caller should free this string
+*/
 char * taginfo_info_get_album(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String album = i->get_album();
         strings.prepend(s);
     return s;
 }
+//! Set the album of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param album Album as const char *.
+*/
 void taginfo_info_set_album(TagInfo_Info *info, const char *album) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_album(String(album, String::UTF8));
 }
 
+//! Get the title of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The title as char *. In case the string management is not enabled, the caller should free this string
+*/
 char * taginfo_info_get_title(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String title = i->get_title();
         strings.prepend(s);
     return s;
 }
+//! Set the title of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param title Title as const char *.
+*/
 void taginfo_info_set_title(TagInfo_Info *info, const char *title) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_title(String(title, String::UTF8));
 }
 
+//! Get the albumartist tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The albumartist as char *. In case the string management is not enabled, the caller should free this string
+*/
 char * taginfo_info_get_albumartist(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String album_artist = i->get_album_artist();
         strings.prepend(s);
     return s;
 }
+//! Set the album artist tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param albumartist Album artist as const char *.
+*/
 void taginfo_info_set_albumartist(TagInfo_Info *info, const char *albumartist) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_album_artist(String(albumartist, String::UTF8));
 }
 
+//! Get the comment tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The comment as char *. In case the string management is not enabled, the caller should free this string
+*/
 char * taginfo_info_get_comment(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String comments = i->get_comments();
         strings.prepend(s);
     return s;
 }
+//! Set the comment of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param comment Comment as const char *.
+*/
 void taginfo_info_set_comment(TagInfo_Info *info, const char *comment) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_comments(String(comment, String::UTF8));
 }
 
+//! Get the composer tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The composer as char *. In case the string management is not enabled, the caller should free this string
+*/
 char * taginfo_info_get_composer(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String composer = i->get_composer();
         strings.prepend(s);
     return s;
 }
+//! Set the composer of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param composer Composer as const char *.
+*/
 void taginfo_info_set_composer(TagInfo_Info *info, const char *composer) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_composer(String(composer, String::UTF8));
 }
 
+//! Get the homepage tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The homepage as char *. In case the string management is not enabled, the caller should free this string
+*/
 char * taginfo_info_get_homepage(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String homepage = i->get_homepage();
         strings.prepend(s);
     return s;
 }
+//! Set the homepage tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param homepage Homepage tag as const char *.
+*/
 void taginfo_info_set_homepage(TagInfo_Info *info, const char *homepage) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_homepage(String(homepage, String::UTF8));
 }
 
+//! Get the encoder tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The encoder as char *. In case the string management is not enabled, the caller should free this string
+*/
 char * taginfo_info_get_encoder(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String encoder = i->get_encoder();
         strings.prepend(s);
     return s;
 }
+//! Set the encoder of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param encoder Encoder tag as const char *.
+*/
 void taginfo_info_set_encoder(TagInfo_Info *info, const char *encoder) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_encoder(String(encoder, String::UTF8));
 }
 
-void taginfo_info_set_copyright(TagInfo_Info *info, const char *copyright) {
-    Info *i = reinterpret_cast<Info *>(info);
-    i->set_copyright(String(copyright, String::UTF8));
-}
+//! Get the copyright tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The copyright as char *. In case the string management is not enabled, the caller should free this string
+*/
 char * taginfo_info_get_copyright(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String copyright = i->get_copyright();
         strings.prepend(s);
     return s;
 }
+//! Set the copyright tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param copyright Copyright tag as const char *.
+*/
+void taginfo_info_set_copyright(TagInfo_Info *info, const char *copyright) {
+    Info *i = reinterpret_cast<Info *>(info);
+    i->set_copyright(String(copyright, String::UTF8));
+}
 
+//! Get the genre tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The genre as char *. In case the string management is not enabled, the caller should free this string
+*/
 char * taginfo_info_get_genre(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String genre = i->get_genre();
         strings.prepend(s);
     return s;
 }
+//! Set the genre tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param genre Genre tag as const char *.
+*/
 void taginfo_info_set_genre(TagInfo_Info *info, const char *genre) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_genre(String(genre, String::UTF8));
 }
 
+//! Get the track number of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The track number as int.
+*/
 int taginfo_info_get_track_number(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     return i->get_track_number();
 }
+//! Set the track number tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param track_number Track number tag as int.
+*/
 void taginfo_info_set_track_number(TagInfo_Info *info, int track_number) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_track_number(track_number);
 }
 
+//! Get the track count of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The track count as int.
+*/
 int taginfo_info_get_track_count(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     return i->get_track_count();
 }
+//! Set the track count tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param track_count Track count tag as int.
+*/
 void taginfo_info_set_track_count(TagInfo_Info *info, int track_count) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_track_count(track_count);
 }
 
+//! Get the publishing year of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\return The year as int.
+*/
 int taginfo_info_get_year(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     return i->get_year();
 }
+//! Set the year tag of a media track.
+//! \param info A TagInfo_Info object
+/*!
+\param year Year tag as int.
+*/
 void taginfo_info_set_year(TagInfo_Info *info, int year) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_year(year);
 }
 
+/*!
+Get the bitrate audio property
+\param info A TagInfo_Info object
+\return The bitrate as int.
+*/
 int taginfo_info_get_bitrate(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     return i->get_bitrate();
 }
 
+/*!
+Get the samplerate audio property
+\param info A TagInfo_Info object
+\return The samplerate as int.
+*/
 int taginfo_info_get_samplerate(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     return i->get_samplerate();
 }
 
+/*!
+Get the channels audio property
+\param info A TagInfo_Info object
+\return The number of channels as int.
+*/
 int taginfo_info_get_channels(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     return i->get_channels();
 }
 
+/*!
+Get the length audio property
+\param info A TagInfo_Info object
+\return The length in seconds as int.
+*/
 int taginfo_info_get_length(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     return i->get_length_seconds();
 }
 
+//! Get information on the availability of an image that is embedded in the media file.
+/*!
+\param info A TagInfo_Info object
+\return TRUE if there is an image
+*/
 BOOL taginfo_info_get_has_image(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     //bool image_available = i->get_has_image();
     return i->get_has_image();
 }
 
+//! Get the volume number of a media track.
+/*!
+\param info A TagInfo_Info object
+\return The volume number as int.
+*/
 int taginfo_info_get_volume_number(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     return i->get_volume_number();
 }
+//! Set the volume number tag of a media track.
+/*!
+\param info A TagInfo_Info object
+\param number Volume number tag as int.
+*/
 void taginfo_info_set_volume_number(TagInfo_Info *info, int number) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_volume_number(number);
 }
 
+//! Get the volume count of a media track.
+/*!
+\param info A TagInfo_Info object
+\return The volume_count as int.
+*/
 int taginfo_info_get_volume_count(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     return i->get_volume_count();
 }
+//! Set the volume count tag of a media track.
+/*!
+\param info A TagInfo_Info object
+\param count Volume count tag as int.
+*/
 void taginfo_info_set_volume_count(TagInfo_Info *info, int count) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_volume_count(count);
 }
 
+//! Get the rating of a media track. rating 1 - 5; 0 -> not set
+/*!
+\param info A TagInfo_Info object
+\return The rating as int.
+*/
 int taginfo_info_get_rating(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     return i->get_rating();
 }
+//! Set the rating tag of a media track. rating 1 - 5; 0 -> not set
+/*!
+\param info A TagInfo_Info object
+\param rating Rating as int.
+*/
 void taginfo_info_set_rating(TagInfo_Info *info, int rating) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_rating(rating);
 }
 
+//! Get the play count of a media track.
+/*!
+\param info A TagInfo_Info object
+\return The play count as int.
+*/
 int  taginfo_info_get_playcount(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     return i->get_playcount();
 }
+//! Set the play count tag of a media track.
+/*!
+\param info A TagInfo_Info object
+\param count Play count tag as int.
+*/
 void taginfo_info_set_playcount(TagInfo_Info *info, int count) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_playcount(count);
 }
 
+//! Get the information if the media file is part of a compilation / VA album.
+/*!
+\param info A TagInfo_Info object
+\return TRUE if it is part of a compilation
+*/
 BOOL taginfo_info_get_is_compilation(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     BOOL s = i->get_is_compilation();
     return s;
 }
+//! Set the information if the media file is part of a compilation / VA album.
+/*!
+\param info A TagInfo_Info object
+\param is_compilation TRUE if it is part of a compilation
+*/
 void taginfo_info_set_is_compilation(TagInfo_Info *info, BOOL is_compilation) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_is_compilation((bool)is_compilation);
 }
 
+//! Get an array of user defined track labels.
+/*!
+\param info A TagInfo_Info object
+\return Array of track labels
+\param labels_length The return location for the length of the returned array.
+*/
 char **taginfo_info_get_track_labels(const TagInfo_Info *info,
                                      int *labels_length) {
     const Info *i = reinterpret_cast<const Info *>(info);
     StringList list = i->get_track_labels_list();
     return string_list_to_c_array(list, labels_length);
 }
+//! Set an array of user defined track labels.
+/*!
+\param info A TagInfo_Info object
+\param labels An array of user defined track labels
+\param labels_length The length of the array
+*/
 void taginfo_info_set_track_labels(TagInfo_Info *info,
                                    const char* const* labels, int labels_length) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_track_labels_list(list);
 }
 
+//! Get an array of user defined album labels.
+/*!
+\param info A TagInfo_Info object
+\return Array of album labels
+\param labels_length The return location for the length of the returned array.
+*/
 char **taginfo_info_get_album_labels(const TagInfo_Info *info,
                                      int *labels_length) {
     const Info *i = reinterpret_cast<const Info *>(info);
     StringList list = i->get_album_labels_list();
     return string_list_to_c_array(list, labels_length);
 }
+//! Set an array of user defined album labels.
+/*!
+\param info A TagInfo_Info object
+\param labels An array of user defined album labels
+\param labels_length The length of the array
+*/
 void taginfo_info_set_album_labels(TagInfo_Info *info,
                                    const char* const* labels, int labels_length) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_album_labels_list(list);
 }
 
+//! Get an array of user defined artist labels.
+/*!
+\param info A TagInfo_Info object
+\return Array of artist labels
+\param labels_length The return location for the length of the returned array.
+*/
 char** taginfo_info_get_artist_labels(const TagInfo_Info *info,
                                       int * labels_length) {
     const Info *i = reinterpret_cast<const Info *>(info);
     StringList list = i->get_artist_labels_list();
     return string_list_to_c_array(list, labels_length);
 }
+//! Set an array of user defined artist labels.
+/*!
+\param labels An array of user defined artist labels
+\param labels_length The length of the array
+*/
 void taginfo_info_set_artist_labels(TagInfo_Info *info,
                                     const char* const* labels, int labels_length) {
     Info *i = reinterpret_cast<Info *>(info);
 
 
 //*****************IMAGES****************************************************************
+//! Get an array of images copied from the file embedded images.
+/*!
+\return Array of TagInfo_Image
+\param info A TagInfo_Info object
+\param image_count The return location for the length of the returned array.
+*/
 TagInfo_Image ** taginfo_info_get_images(const TagInfo_Info *info,
                              int *image_count) {
     const Info *i = reinterpret_cast<const Info *>(info);
     images = reinterpret_cast<TagInfo_Image **> (i->get_images((*image_count)));
     return images;
 }
-
+//! Set an array of TagInfo_Image to be embedded into the media file.
+/*!
+\param info A TagInfo_Info object
+\param labels An array of TagInfo_Image
+\param image_count The length of the TagInfo_Image array
+*/
 void taginfo_info_set_images(TagInfo_Info *info,
                              const TagInfo_Image ** images, const int image_count) {
     Info *i = reinterpret_cast<Info *>(info);
     i->set_images(imgs, image_count);
 }
 
+/*!
+ * Frees a TagInfo_Image object.
+ */
+//!\param img A TagInfo_Image object
 void taginfo_image_free(TagInfo_Image * img) {
     if(!img)
         return;
     delete i;
 }
 
+/*!
+ * Frees an array of TagInfo_Image as returned from taginfo_info_get_images()..
+ */
+//!\param img A TagInfo_Image object
 void taginfo_image_array_free(TagInfo_Image ** img_arr) {
     if(!img_arr)
         return;
 
 
 //*****************LYRICS****************************************************************
+//! Get a lyrics string from the media file.
+/*!
+\return Lyrics string
+*/
+//! \param info A TagInfo_Info object
 char * taginfo_info_get_lyrics(const TagInfo_Info *info) {
     const Info *i = reinterpret_cast<const Info *>(info);
     String lyrics = i->get_lyrics();
     return s;
 }
 
+//! Set a lyrics string to the media file.
+/*!
+\param lyrics Lyrics string
+*/
+//! \param info A TagInfo_Info object
 BOOL taginfo_info_set_lyrics(TagInfo_Info *info, const char * lyrics) {
     Info *i = reinterpret_cast<Info *>(info);
     return i->set_lyrics(String(lyrics, String::UTF8));

bindings/c/taginfo_c.h

 /**
  * @mainpage
  *
- * This manual documents the <em>C bindings</em> for the libtaginfo C API. 
- * libtaginfo is a wrapper library for taglib and alows access to media tags in an abstract way.
- *
+ * This manual documents the <b><em>C bindings</em></b> for libtaginfo. Libtaginfo is a wrapper library for 
+ * taglib and allows access to media tags in an abstract way.
+ * 
+ * The functions used to interface the library through C language is available from the taginfo_c.h header.
  *
  * Known tag formats are: 
  *  - Ape tags, 
 #endif
 
 
-//! \class TagInfo_Info is an abstraction for accessing media file tags
-typedef struct { int dummy; } TagInfo_Info;
-
-
 //! \enum TagInfo_ImageFileType is an enumeration of image file types for embedded images
 typedef enum {
-  TagInfo_IMAGE_FILE_TYPE_UNKNOWN,
-  TagInfo_IMAGE_FILE_TYPE_JPEG,
-  TagInfo_IMAGE_FILE_TYPE_PNG,
-  TagInfo_IMAGE_FILE_TYPE_BMP,
-  TagInfo_IMAGE_FILE_TYPE_GIF
+        //! Unknown image file type
+    TAG_INFO_IMAGE_FILE_TYPE_UNKNOWN,
+        //! Jpg file type
+    TAG_INFO_IMAGE_FILE_TYPE_JPEG,
+        //! Png file type
+    TAG_INFO_IMAGE_FILE_TYPE_PNG,
+        //! Gif file type
+    TAG_INFO_IMAGE_FILE_TYPE_GIF,
+        //! Bitmap file type
+    TAG_INFO_IMAGE_FILE_TYPE_BMP
 } TagInfo_ImageFileType;
 
 //! \enum TagInfo_MediaFileType is an enumeration of media file types supported in libtaginfo
 typedef enum {
-    MEDIA_FILE_TYPE_UNKNOWN,
-    MEDIA_FILE_TYPE_AAC,
-    MEDIA_FILE_TYPE_AIF,
-    MEDIA_FILE_TYPE_APE,
-    MEDIA_FILE_TYPE_ASF,
-    MEDIA_FILE_TYPE_FLAC,
-    MEDIA_FILE_TYPE_M4A,
-    MEDIA_FILE_TYPE_M4B,
-    MEDIA_FILE_TYPE_M4P,
-    MEDIA_FILE_TYPE_MP3,
-    MEDIA_FILE_TYPE_MP4,
-    MEDIA_FILE_TYPE_MPC,
-    MEDIA_FILE_TYPE_OGA,
-    MEDIA_FILE_TYPE_OGG,
-    MEDIA_FILE_TYPE_TTA,
-    MEDIA_FILE_TYPE_WAV,
-    MEDIA_FILE_TYPE_WMA,
-    MEDIA_FILE_TYPE_WV,
-    MEDIA_FILE_TYPE_SPEEX,
-    MEDIA_FILE_TYPE_WMV,
-    MEDIA_FILE_TYPE_MOD,
-    MEDIA_FILE_TYPE_IT,
-    MEDIA_FILE_TYPE_XM,
-    MEDIA_FILE_TYPE_S3M
+    //! Unknown media file type
+    TAG_INFO_MEDIA_FILE_TYPE_UNKNOWN, 
+    //! Aac media file
+    TAG_INFO_MEDIA_FILE_TYPE_AAC,
+    //! Aiff media file
+    TAG_INFO_MEDIA_FILE_TYPE_AIF,
+    //! Ape media file
+    TAG_INFO_MEDIA_FILE_TYPE_APE,
+    //! Asf media file
+    TAG_INFO_MEDIA_FILE_TYPE_ASF,
+    //! Flac media file
+    TAG_INFO_MEDIA_FILE_TYPE_FLAC,
+    //! M4A media file
+    TAG_INFO_MEDIA_FILE_TYPE_M4A,
+    //! M4B media file
+    TAG_INFO_MEDIA_FILE_TYPE_M4B,
+    //! M4P media file
+    TAG_INFO_MEDIA_FILE_TYPE_M4P,
+    //! MP3 media file
+    TAG_INFO_MEDIA_FILE_TYPE_MP3,
+    //! MP4 media file
+    TAG_INFO_MEDIA_FILE_TYPE_MP4,
+    //! MPC media file
+    TAG_INFO_MEDIA_FILE_TYPE_MPC,
+    //! Oga media file
+    TAG_INFO_MEDIA_FILE_TYPE_OGA,
+    //! Ogg media file
+    TAG_INFO_MEDIA_FILE_TYPE_OGG,
+    //! Tta media file
+    TAG_INFO_MEDIA_FILE_TYPE_TTA,
+    //! Wave media file
+    TAG_INFO_MEDIA_FILE_TYPE_WAV,
+    //! Wma media file
+    TAG_INFO_MEDIA_FILE_TYPE_WMA,
+    //! WavPack media file
+    TAG_INFO_MEDIA_FILE_TYPE_WV,
+    //! Speex media file
+    TAG_INFO_MEDIA_FILE_TYPE_SPEEX,
+    //! Wmv media file
+    TAG_INFO_MEDIA_FILE_TYPE_WMV,
+    //! Mod media file
+    TAG_INFO_MEDIA_FILE_TYPE_MOD,
+    //! Impulse Tracker media file
+    TAG_INFO_MEDIA_FILE_TYPE_IT,
+    //! Xm media file
+    TAG_INFO_MEDIA_FILE_TYPE_XM,
+    //! S3m media file
+    TAG_INFO_MEDIA_FILE_TYPE_S3M
 } TagInfo_MediaFileType;
 
 //! \enum TagInfo_ImageType enumeration for image content description
 typedef enum {
     //! An image type not listed here
-    IMAGE_TYPE_OTHER,
+    TAG_INFO_IMAGE_TYPE_OTHER,
     //! 32x32 PNG image that should be used as the file icon
-    IMAGE_TYPE_FILE_ICON,
+    TAG_INFO_IMAGE_TYPE_FILE_ICON,
     //! File icon of a different size or format
-    IMAGE_TYPE_OTHER_FILE_ICON,
+    TAG_INFO_IMAGE_TYPE_OTHER_FILE_ICON,
     //! Front cover image of the album
-    IMAGE_TYPE_COVER_FRONT,
+    TAG_INFO_IMAGE_TYPE_COVER_FRONT,
     //! Back cover image of the album
-    IMAGE_TYPE_COVER_BACK,
+    TAG_INFO_IMAGE_TYPE_COVER_BACK,
     //! Inside leaflet page of the album
-    IMAGE_TYPE_LEAFLET_PAGE,
+    TAG_INFO_IMAGE_TYPE_LEAFLET_PAGE,
     //! Image from the album itself
-    IMAGE_TYPE_MEDIA,
+    TAG_INFO_IMAGE_TYPE_MEDIA,
     //! Picture of the lead artist or soloist
-    IMAGE_TYPE_LEAD_ARTIST,
+    TAG_INFO_IMAGE_TYPE_LEAD_ARTIST,
     //! Picture of the artist or performer
-    IMAGE_TYPE_ARTIST,
+    TAG_INFO_IMAGE_TYPE_ARTIST,
     //! Picture of the conductor
-    IMAGE_TYPE_CONDUCTOR,
+    TAG_INFO_IMAGE_TYPE_CONDUCTOR,
     //! Picture of the band or orchestra
-    IMAGE_TYPE_BAND,
+    TAG_INFO_IMAGE_TYPE_BAND,
     //! Picture of the composer
-    IMAGE_TYPE_COMPOSER,
+    TAG_INFO_IMAGE_TYPE_COMPOSER,
     //! Picture of the lyricist or text writer
-    IMAGE_TYPE_LYRICIST,
+    TAG_INFO_IMAGE_TYPE_LYRICIST,
     //! Picture of the recording location or studio
-    IMAGE_TYPE_RECORDING_LOCATION,
+    TAG_INFO_IMAGE_TYPE_RECORDING_LOCATION,
     //! Picture of the artists during recording
-    IMAGE_TYPE_DURING_RECORDING,
+    TAG_INFO_IMAGE_TYPE_DURING_RECORDING,
     //! Picture of the artists during performance
-    IMAGE_TYPE_DURING_PERFORMANCE,
+    TAG_INFO_IMAGE_TYPE_DURING_PERFORMANCE,
     //! Picture from a movie or video related to the track
-    IMAGE_TYPE_MOVIESCREENCAPTURE,
+    TAG_INFO_IMAGE_TYPE_MOVIESCREENCAPTURE,
     //! Picture of a large, coloured fish.
-    IMAGE_TYPE_COLOURED_FISH,
+    TAG_INFO_IMAGE_TYPE_COLOURED_FISH,
     //! Illustration related to the track
-    IMAGE_TYPE_ILLUSTRATION,
+    TAG_INFO_IMAGE_TYPE_ILLUSTRATION,
     //! Logo of the band or performer
-    IMAGE_TYPE_ARTIST_LOGO,
+    TAG_INFO_IMAGE_TYPE_ARTIST_LOGO,
     //! Logo of the publisher (record company)
-    IMAGE_TYPE_PUBLISHER_LOGO
+    TAG_INFO_IMAGE_TYPE_PUBLISHER_LOGO
 } TagInfo_ImageType;
 
 
-//! \class TagInfo_Image contains image data and image information
+//! \class TagInfo_Info is an abstraction for accessing media file tags. 
+//! The caller should destroy TagInfo_Info with taginfo_info_free() after usage. Internal data will then automatically be removed.
+typedef struct { 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+    int dummy; 
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+} TagInfo_Info;
+
+
+//! \class TagInfo_Image contains image data and image information. 
+//! The caller should destroy TagInfo_Image with taginfo_image_free() after usage. Internal data will then automatically be removed.
 typedef struct { 
     char *                  data;
     unsigned long           data_length;
 } TagInfo_Image;
 
 
-// FACTORY CREATION
-/*!
- * Creates a TagInfo file based on \a filename.  TagInfo will try to guess the file
- * type.
- *
- * \return NULL if the file type cannot be determined or the file cannot
- * be opened. The returned object should be freed with taginfo_info_free() after usage
- */
-TagInfo_Info *taginfo_info_factory_make(const char *filename);
+//FREE FUNCTIONS
+void taginfo_info_free(TagInfo_Info *info);
 
-TagInfo_Info *taginfo_info_factory_make_with_format(const char *filename, TagInfo_MediaFileType format);
+void taginfo_image_free(TagInfo_Image * img);
+void taginfo_image_array_free(TagInfo_Image ** img_arr);
 
-TagInfo_Info *taginfo_info_factory_make_from_mime(const char *filename, const char *mime_type);
 
-/*!
- * Frees an info object.
- */
-void taginfo_info_free(TagInfo_Info *info);
 
-/*!
- * Frees an image object.
- */
-void taginfo_image_free(TagInfo_Image * img);
+// FACTORY CREATION
+TagInfo_Info *taginfo_info_create_tag_info(const char *filename);
+TagInfo_Info *taginfo_info_create_tag_info_with_format(const char *filename, TagInfo_MediaFileType format);
+TagInfo_Info *taginfo_info_create_tag_info_from_mime(const char *filename, const char *mime_type);
 
-/*!
- * Frees an image array as returned from taginfo_info_get_images().
- */
-void taginfo_image_array_free(TagInfo_Image ** img_arr);
 
-// READ / WRITE
+// LOAD / SAVE
 BOOL taginfo_info_load(TagInfo_Info *info);
 BOOL taginfo_info_save(TagInfo_Info *info);
 
 
 // STRING MANAGEMENT
-//! Enable string management for libtaginfo
 void taginfo_info_enable_string_management(BOOL management);
-
-//! clean up used strings
-//! To be used in case string management is used
 void taginfo_info_free_strings();
 
 
 // TAG ACCESS
-
-//! Get the album tag of a media track.
-/*!
-\return The album as char *. In case the string management is not enabled, the caller should free this string
-*/
 char *taginfo_info_get_album(const TagInfo_Info *info);
 void  taginfo_info_set_album(TagInfo_Info *info, const char *album);
 
-//! Get the albumartist tag of a media track.
-/*!
-\return The albumartist as char *. In case the string management is not enabled, the caller should free this string
-*/
 char *taginfo_info_get_albumartist(const TagInfo_Info *info);
 void  taginfo_info_set_albumartist(TagInfo_Info *info, const char *albumartist);
 
-//! Get the artist tag of a media track.
-/*!
-\return The artist as char *. In case the string management is not enabled, the caller should free this string
-*/
 char *taginfo_info_get_artist(const TagInfo_Info *info);
 void  taginfo_info_set_artist(TagInfo_Info *info, const char *artist);
 
-//! Get the comment tag of a media track.
-/*!
-\return The comment as char *. In case the string management is not enabled, the caller should free this string
-*/
 char *taginfo_info_get_comment(const TagInfo_Info *info);
 void  taginfo_info_set_comment(TagInfo_Info *info, const char *comment);
 
-//! Get the composer tag of a media track.
-/*!
-\return The composer as char *. In case the string management is not enabled, the caller should free this string
-*/
 char *taginfo_info_get_composer(const TagInfo_Info *info);
 void  taginfo_info_set_composer(TagInfo_Info *info, const char *composer);
 
-//! Get the copyright tag of a media track.
-/*!
-\return The copyright as char *. In case the string management is not enabled, the caller should free this string
-*/
 char *taginfo_info_get_copyright(const TagInfo_Info *info);
 void  taginfo_info_set_copyright(TagInfo_Info *info, const char *copyright);
 
-//! Get the encoder tag of a media track.
-/*!
-\return The encoder as char *. In case the string management is not enabled, the caller should free this string
-*/
 char *taginfo_info_get_encoder(const TagInfo_Info *info);
 void  taginfo_info_set_encoder(TagInfo_Info *info, const char *encoder);
 
-//! Get the genre tag of a media track.
-/*!
-\return The genre as char *. In case the string management is not enabled, the caller should free this string
-*/
 char *taginfo_info_get_genre(const TagInfo_Info *info);
 void  taginfo_info_set_genre(TagInfo_Info *info, const char *genre);
 
 BOOL taginfo_info_get_has_image(const TagInfo_Info *info);
 
-//! Get the homepage tag of a media track.
-/*!
-\return The homepage as char *. In case the string management is not enabled, the caller should free this string
-*/
 char *taginfo_info_get_homepage(const TagInfo_Info *info);
 void  taginfo_info_set_homepage(TagInfo_Info *info, const char *homepage);
 
 BOOL taginfo_info_get_is_compilation(const TagInfo_Info *info);
 void taginfo_info_set_is_compilation(TagInfo_Info *info, BOOL is_compilation);
 
-//! Get the original_artist tag of a media track.
-/*!
-\return The original_artist as char *. In case the string management is not enabled, the caller should free this string
-*/
 char *taginfo_info_get_original_artist(const TagInfo_Info *info);
 void  taginfo_info_set_original_artist(TagInfo_Info *info, const char *artist);
 
-
 int  taginfo_info_get_playcount(const TagInfo_Info *info);
 void taginfo_info_set_playcount(TagInfo_Info *info, int count);
 
 int  taginfo_info_get_rating(const TagInfo_Info *info);
 void taginfo_info_set_rating(TagInfo_Info *info, int rating);
 
-//! Get the title tag of a media track.
-/*!
-\return The title as char *. In case the string management is not enabled, the caller should free this string
-*/
 char *taginfo_info_get_title(const TagInfo_Info *info);
 void  taginfo_info_set_title(TagInfo_Info *info, const char *title);
 
-//! Get the track count of a media track.
-/*!
-\return The track count as int.
-*/
 int  taginfo_info_get_track_count(const TagInfo_Info *info);
 void taginfo_info_set_track_count(TagInfo_Info *info, int track_number);
 
-//! Get the track number of a media track.
-/*!
-\return The track number as int.
-*/
 int  taginfo_info_get_track_number(const TagInfo_Info *info);
 void taginfo_info_set_track_number(TagInfo_Info *info, int track_number);
 
-//! Get the volume count of a media track.
-/*!
-\return The volume count as int.
-*/
 int taginfo_info_get_volume_count(const TagInfo_Info *info);
 void taginfo_info_set_volume_count(TagInfo_Info *info, int count);
 
-//! Get the volume number of a media track.
-/*!
-\return The volume number as int.
-*/
 int taginfo_info_get_volume_number(const TagInfo_Info *info);
 void taginfo_info_set_volume_number(TagInfo_Info *info, int number);
 
-//! Get the year of a media track.
-/*!
-\return The year as int.
-*/
 int taginfo_info_get_year(const TagInfo_Info *info);
 void taginfo_info_set_year(TagInfo_Info *info, int year);
 

bindings/vala/libtaginfo_c.vapi

 [CCode (cprefix = "TagInfo_", lower_case_cprefix = "taginfo_", cheader_filename = "taginfo_c.h")]
 namespace TagInfo
 {
-	[CCode (cname = "TagInfo_ImageFileType", cprefix = "TagInfo_IMAGE_FILE_TYPE_")]
+	[CCode (cname = "TagInfo_ImageFileType", cprefix = "TAG_INFO_IMAGE_FILE_TYPE_")]
 	public enum ImageFileType
 	{
 		UNKNOWN,
 		JPEG,
 		PNG,
-		BMP,
-		GIFS
+		GIF,
+		BMP
 	}
 	
-	[CCode (cname = "TagInfo_MediaFileType", cprefix = "MEDIA_FILE_TYPE_")]
+	[CCode (cname = "TagInfo_MediaFileType", cprefix = "TAG_INFO_MEDIA_FILE_TYPE_")]
 	public enum MediaFileType
 	{
 		UNKNOWN,
 		S3M
 	}
 	
-	[CCode (cname = "TagInfo_ImageType", cprefix = "IMAGE_TYPE_")]
+	[CCode (cname = "TagInfo_ImageType", cprefix = "TAG_INFO_IMAGE_TYPE_")]
 	public enum ImageType
 	{
 		//! An image type not listed here
 		PUBLISHER_LOGO
 	}
 	
-	[CCode (free_function = "taginfo_image_free")]
 	[Compact]
+	[CCode (free_function = "taginfo_image_free")]
 	public class Image
 	{
 		[CCode (array_length_cname = "data_length", array_length_type = "ulong")]
 		public char*            description;
 	}
 
-	[CCode (free_function = "taginfo_info_free")]
 	[Compact]
+	[CCode (free_function = "taginfo_info_free")]
 	protected class Info
 	{
 		//creation method using filename extension
-		public static Info factory_make (string filename);
+		public static Info create_tag_info (string filename);
 		
 		//creation method for known formats/mimetypes
-		public static Info factory_make_with_format (string filename, MediaFileType media_file_type);
+		public static Info create_tag_info_with_format (string filename, MediaFileType media_file_type);
 		
 		//creation method using mimetype
-		public static Info factory_make_from_mime (string filename, string mimetype);
+		public static Info create_tag_info_from_mime (string filename, string mimetype);
 		
 		public bool load ();
 		
 # configuration options related to the input files
 #---------------------------------------------------------------------------
 INPUT                  = ../bindings/c/
-FILE_PATTERNS          = *.c *.h
+FILE_PATTERNS          = *.cc *.h
 RECURSIVE              = YES
 #EXCLUDE                = test
 
 #---------------------------------------------------------------------------
 GENERATE_MAN           = NO
 MAN_OUTPUT             = man
-MAN_EXTENSION          = .3dbus
+MAN_EXTENSION          = .3taginfo_c
 MAN_LINKS              = YES
 #---------------------------------------------------------------------------
 # configuration options related to the XML output
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           = 
 INCLUDE_FILE_PATTERNS  = 
-PREDEFINED             = "DBUS_BEGIN_DECLS=" 			\
-			 "DBUS_END_DECLS=" 			\
-			 "DOXYGEN_SHOULD_SKIP_THIS" 		\
-                         "DBUS_GNUC_DEPRECATED="                \
-			 "_DBUS_DEFINE_GLOBAL_LOCK(name)="	\
-			 "_DBUS_GNUC_PRINTF(from,to)="
+PREDEFINED             = "DOXYGEN_SHOULD_SKIP_THIS"
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
 # Configuration::addtions related to external references   

docs/Doxyfile_c.in

 # configuration options related to the input files
 #---------------------------------------------------------------------------
 INPUT                  = @top_srcdir@/bindings/c/
-FILE_PATTERNS          = *.c *.h
+FILE_PATTERNS          = *.cc *.h
 RECURSIVE              = YES
 #EXCLUDE                = test
 
 #---------------------------------------------------------------------------
 GENERATE_MAN           = NO
 MAN_OUTPUT             = man
-MAN_EXTENSION          = .3dbus
+MAN_EXTENSION          = .3taginfo_c
 MAN_LINKS              = YES
 #---------------------------------------------------------------------------
 # configuration options related to the XML output
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           = 
 INCLUDE_FILE_PATTERNS  = 
-PREDEFINED             = "DBUS_BEGIN_DECLS=" 			\
-			 "DBUS_END_DECLS=" 			\
-			 "DOXYGEN_SHOULD_SKIP_THIS" 		\
-                         "DBUS_GNUC_DEPRECATED="                \
-			 "_DBUS_DEFINE_GLOBAL_LOCK(name)="	\
-			 "_DBUS_GNUC_PRINTF(from,to)="
+PREDEFINED             = "DOXYGEN_SHOULD_SKIP_THIS"
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
 # Configuration::addtions related to external references   

libtaginfo/taginfo.h

 
 /*! \mainpage TagInfo Documentation
  * 
- * libtaginfo is a wrapper library for taglib and alows access to media tags in an abstract way.
+ * <b>libtaginfo is a wrapper library for taglib</b> and alows access to media tags in an abstract way.
+ * 
  * C and vala bindings for the C++ API are coming with this library.
  * 
  * Known tag formats are: 
 
  /*!
   * 
-  * Contains classes for abstract access to media file tags.
+  * The \namespace TagInfo contains classes for abstract access to media file tags.
   */
 namespace TagInfo {
     
-    //! The enumeration type for the media file type
+    //! \enum MediaFileType describes the media file type
     /*! Enumerator for the type of the media file. */
     enum MediaFileType {
         //! Unknown media file type
     //! A simple, generic interface to common audio meta data fields
     
     /*!
-    * This is an attempt to abstract away the difference in the meta data formats
+    * \class Info is an attempt to abstract away the difference in the meta data formats
     * of various audio codecs and tagging schemes.  
     */
     class Info {
              */
             static Info * create_tag_info_from_mime(const String &filename, const String &mime_type);
     };
-    
-    
-
 }
 #endif

tests/ctest_read/main.c

     TagInfo_Info *info;
     
     char val[200] = TESTDIR "samples/sample.flac";
-    info = taginfo_info_factory_make(val);
+    info = taginfo_info_create_tag_info(val);
     if(info == NULL)
         return 1; //EXIT_FAILURE
     

tests/ctest_write/main.c

     if(cp(s, target) < 0)
         return 1; //EXIT_FAILURE
     
-    info = taginfo_info_factory_make(target);
+    info = taginfo_info_create_tag_info(target);
     
     if(info == NULL)
         return 1; //EXIT_FAILURE
     taginfo_info_set_track_labels(info, (const char * const*)labels, labels_length);
     taginfo_info_save(info);
     taginfo_info_free(info);
-    info = taginfo_info_factory_make(target);
+    info = taginfo_info_create_tag_info(target);
     int j = 0;
     if(taginfo_info_load(info)) {
         int out_labels_length_artist = 0;