Add PhotoDB functions to the docs.

Incorporate usage overviews from README into the docs.
Fix a few doc comments to allow gtk-doc to parse them.


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

8 files changed, 547 insertions, 17 deletions

diff --git a/docs/reference/libgpod-docs.xml b/docs/reference/libgpod-docs.xml
index bb66747..d80fd43 100644
--- a/docs/reference/libgpod-docs.xml
+++ b/docs/reference/libgpod-docs.xml
@@ -52,25 +52,54 @@
     </legalnotice>
 
     <abstract>
-      <para>This manual documents the interfaces of the libgpod
-      library and has some short notes to help get you up to speed
-      with using the library.</para>
+      <para>
+      This manual documents the interfaces of the libgpod library and
+      has some short notes to help get you up to speed with using the
+      library.
+      </para>
+      <para>
+      Please see the programs in the <ulink type="http"
+      url="http://gtkpod.cvs.sourceforge.net/gtkpod/libgpod/tests/">tests/</ulink>
+      directory of the source distribution for some usage examples.  A more
+      complete example can be found in the source for <ulink type="http"
+      url="http://www.gtkpod.org"> Gtkpod</ulink>.  You can also ask questions
+      on the developer's mailing list: <ulink
+      url="mailto:gtkpod-devel@lists.sourceforge.net">gtkpod-devel@lists.sourceforge.net</ulink>.
+      </para>
     </abstract>
   </bookinfo>
 
-  <chapter>
+  <part id="itunesdb">
     <title>iPod database</title>
+    <partintro>
+      <para>
+      The iPod database functions are used for adding audio and video
+      to the iPod.
+      </para>
+    </partintro>
+
     <xi:include href="xml/itunesdb-db.xml"/>
     <xi:include href="xml/itunesdb-copying.xml"/>
     <xi:include href="xml/itunesdb-time.xml"/>
     <xi:include href="xml/itunesdb-lowlevel.xml"/>
-  </chapter>
-  <chapter>
-    <title>iPod database components</title>
-    <xi:include href="xml/track.xml"/>
-    <xi:include href="xml/playlists.xml"/>
-    <xi:include href="xml/smart-playlists.xml"/>
-    <xi:include href="xml/artwork.xml"/>
-    <xi:include href="xml/device.xml"/>
-  </chapter>
+    <chapter>
+      <title>iPod database components</title>
+      <xi:include href="xml/track.xml"/>
+      <xi:include href="xml/playlists.xml"/>
+      <xi:include href="xml/smart-playlists.xml"/>
+      <xi:include href="xml/artwork.xml"/>
+      <xi:include href="xml/device.xml"/>
+    </chapter>
+  </part>
+
+  <part id="photodb">
+    <title>Photo database</title>
+    <partintro>
+      <para>
+      The Photo database functions are used for adding pictures to
+      the iPod.
+      </para>
+    </partintro>
+    <xi:include href="xml/photodb.xml"/>
+  </part>
 </book>
diff --git a/docs/reference/libgpod-sections.txt b/docs/reference/libgpod-sections.txt
index da8b518..83dbace 100644
--- a/docs/reference/libgpod-sections.txt
+++ b/docs/reference/libgpod-sections.txt
@@ -185,6 +185,24 @@ itdb_thumb_new
 itdb_thumb_get_filename
 </SECTION>
 
+<SECTION>
+<FILE>photodb</FILE>
+<TITLE>Photo database</TITLE>
+Itdb_PhotoAlbum
+Itdb_PhotoDB
+itdb_photodb_add_photo
+itdb_photodb_add_photo_from_data
+itdb_photodb_create
+itdb_photodb_free
+itdb_photodb_parse
+itdb_photodb_photoalbum_add_photo
+itdb_photodb_photoalbum_by_name
+itdb_photodb_photoalbum_create
+itdb_photodb_photoalbum_remove
+itdb_photodb_remove_photo
+itdb_photodb_write
+</SECTION>
+
 
 
 
diff --git a/docs/reference/tmpl/artwork.sgml b/docs/reference/tmpl/artwork.sgml
index 023b0e1..32a7679 100644
--- a/docs/reference/tmpl/artwork.sgml
+++ b/docs/reference/tmpl/artwork.sgml
@@ -2,16 +2,18 @@
 Artwork
 
 <!-- ##### SECTION Short_Description ##### -->
-Data structure to store iPod artwork (album covers and photos)
+Data structure to store iPod artwork (album covers)
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-These functions and structures are for adding, changing, and removing artwork.
+These functions and structures are for adding, changing, and removing
+album/track artwork.  For working with photos, see the
+<link linkend="photodb">Photo database</link> section.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+<link linkend="photodb">Photo database</link>
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->
@@ -102,6 +104,20 @@ These functions and structures are for adding, changing, and removing artwork.
 @Returns: 
 
 
+<!-- ##### FUNCTION itdb_artwork_add_thumbnail_from_data ##### -->
+<para>
+
+</para>
+
+@artwork: 
+@type: 
+@image_data: 
+@image_data_len: 
+@rotation: 
+@error: 
+@Returns: 
+
+
 <!-- ##### FUNCTION itdb_artwork_remove_thumbnail ##### -->
 <para>
 
diff --git a/docs/reference/tmpl/device.sgml b/docs/reference/tmpl/device.sgml
index 36d2778..d90303e 100644
--- a/docs/reference/tmpl/device.sgml
+++ b/docs/reference/tmpl/device.sgml
@@ -72,6 +72,98 @@ These functions are for reading and setting information about the iPod.
 @Returns: 
 
 
+<!-- ##### FUNCTION itdb_device_set_sysinfo ##### -->
+<para>
+
+</para>
+
+@device: 
+@field: 
+@value: 
+
+
+<!-- ##### FUNCTION itdb_device_write_sysinfo ##### -->
+<para>
+
+</para>
+
+@device: 
+@error: 
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_device_get_ipod_info ##### -->
+<para>
+
+</para>
+
+@device: 
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_info_get_ipod_info_table ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_info_get_ipod_generation_string ##### -->
+<para>
+
+</para>
+
+@generation: 
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_info_get_ipod_model_name_string ##### -->
+<para>
+
+</para>
+
+@model: 
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_init_ipod ##### -->
+<para>
+
+</para>
+
+@mountpoint: 
+@model_number: 
+@ipod_name: 
+@error: 
+@Returns: 
+
+
+<!-- ##### ENUM Itdb_IpodGeneration ##### -->
+<para>
+
+</para>
+
+@ITDB_IPOD_GENERATION_UNKNOWN: 
+@ITDB_IPOD_GENERATION_FIRST: 
+@ITDB_IPOD_GENERATION_SECOND: 
+@ITDB_IPOD_GENERATION_THIRD: 
+@ITDB_IPOD_GENERATION_FOURTH: 
+@ITDB_IPOD_GENERATION_FIFTH: 
+@ITDB_IPOD_GENERATION_SIXTH: 
+@ITDB_IPOD_GENERATION_MOBILE: 
+
+<!-- ##### STRUCT Itdb_IpodInfo ##### -->
+<para>
+
+</para>
+
+@model_number: 
+@capacity: 
+@ipod_model: 
+@ipod_generation: 
+@musicdirs: 
+
 <!-- ##### ENUM Itdb_IpodModel ##### -->
 <para>
 
diff --git a/docs/reference/tmpl/itunesdb-db.sgml b/docs/reference/tmpl/itunesdb-db.sgml
index ef5db40..d49d074 100644
--- a/docs/reference/tmpl/itunesdb-db.sgml
+++ b/docs/reference/tmpl/itunesdb-db.sgml
@@ -9,6 +9,86 @@ Functions to create, read, write the iPod database
 These functions are for creating, reading, writing, and deleting the iPod
 database and getting the total number of tracks and playlists.
 </para>
+<para>
+Overview of using the iPod database:
+</para>
+<para>
+itdb_parse(): read the iTunesDB and ArtworkDB
+</para>
+<para>
+itdb_write(): write the iTunesDB and ArtworkDB
+</para>
+<para>
+itdb_parse() will return a #Itdb_iTunesDB structure with GLists
+containing all tracks (each track is represented by a #Itdb_Track
+structure) and the playlists (each playlist is represented by a
+#Itdb_Playlist structure).
+</para>
+<para>
+A number of functions for adding, removing, duplicating tracks
+are available.  Please see
+<link linkend="libgpod-Tracks">Tracks</link> for details.
+</para>
+<para>
+In each #Itdb_Playlist structure you can find a GList called
+'members' with listing all member tracks. Each track referenced
+in a playlist must also be present in the tracks GList of the
+iTunesDB.
+</para>
+<para>
+The iPod must contain one master playlist (MPL) containing all
+tracks accessible on the iPod through the
+Music->Tracks/Albums/Artists... menu. Besides the MPL there can
+be a number of normal playlists accessible through the
+Music->Playlists menu on the iPod. Tracks that are a member of
+one of these normal playlists must also be a member of the MPL.
+</para>
+<para>
+The Podcasts playlist is just another playlist with some
+internal flags set differently. Also, member tracks in the
+Podcasts playlist are not normally members of the MPL (so on the
+iPod they will only show up under the Podcasts menu). All tracks
+referenced must be in the tracklist of the #Itdb_iTunesDB,
+however.
+</para>
+<para>
+A number of functions to add/remove playlists, or add/remove
+tracks are available. Please see
+<link linkend="libgpod-Playlists">Playlists</link> for details.
+</para>
+<para>
+Each track can have a thumbnail associated with it. You can
+retrieve a GdkPixmap of the thumbnail using
+itdb_thumb_get_gdk_pixbuf() (tracks have thumbnails of the
+following types associated: @ITDB_THUMB_COVER_SMALL and
+@ITDB_THUMB_COVER_LARGE).  You can remove a thumbnail with
+itdb_track_remove_thumbnails().  And finally, you can set a
+new thumbnail using itdb_track_set_thumbnails().
+</para>
+<para>
+Please note that iTunes additionally stores the artwork as tags
+in the original music file. That's also from where the data is
+read when artwork is displayed in iTunes, and there can be more
+than one piece of artwork. libgpod does not store the artwork as
+tags in the original music file. As a consequence, if you iTunes
+attempts to access the artwork, it will find none, and remove
+libgpod's artwork. Luckily, iTunes will only attempt to access
+the artwork if you select a track in Tunes. (To work around
+this, gtkpod keeps a list of the original filename of all
+artwork and silently adds the thumbnails if they were 'lost'.
+Your application might want to do something similar, or you can
+supply patches for optionally! adding tags to the original music
+files.)
+</para>
+<para>
+The #Itdb_iTunesDB, #Itdb_Playlist and #Itdb_Track structures each
+have a userdata and a usertype field that can be used by the
+application to store application-specific additional data. If
+userdata is a pointer to an external structure, you can supply a
+#ItdbUserDataDuplicateFunc and a #ItdbUserDataDestroyFunc so that
+this data can be duplicated or freed automatically with a call
+to the library _duplicate()/_free() functions.
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
@@ -82,7 +162,7 @@ database and getting the total number of tracks and playlists.
 
 </para>
 
-@db: 
+@itdb: 
 @error: 
 @Returns: 
 
diff --git a/docs/reference/tmpl/itunesdb-lowlevel.sgml b/docs/reference/tmpl/itunesdb-lowlevel.sgml
index 2f70b23..5db32dd 100644
--- a/docs/reference/tmpl/itunesdb-lowlevel.sgml
+++ b/docs/reference/tmpl/itunesdb-lowlevel.sgml
@@ -63,6 +63,15 @@ control over the iPod database.
 @Returns: 
 
 
+<!-- ##### FUNCTION itdb_get_photos_dir ##### -->
+<para>
+
+</para>
+
+@mountpoint: 
+@Returns: 
+
+
 <!-- ##### FUNCTION itdb_get_itunesdb_path ##### -->
 <para>
 
@@ -72,6 +81,15 @@ control over the iPod database.
 @Returns: 
 
 
+<!-- ##### FUNCTION itdb_get_itunessd_path ##### -->
+<para>
+
+</para>
+
+@mountpoint: 
+@Returns: 
+
+
 <!-- ##### FUNCTION itdb_get_artworkdb_path ##### -->
 <para>
 
@@ -81,6 +99,24 @@ control over the iPod database.
 @Returns: 
 
 
+<!-- ##### FUNCTION itdb_get_photodb_path ##### -->
+<para>
+
+</para>
+
+@mountpoint: 
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_get_photos_thumb_dir ##### -->
+<para>
+
+</para>
+
+@mountpoint: 
+@Returns: 
+
+
 <!-- ##### FUNCTION itdb_get_path ##### -->
 <para>
 
diff --git a/docs/reference/tmpl/photodb.sgml b/docs/reference/tmpl/photodb.sgml
new file mode 100644
index 0000000..24032bb
--- /dev/null
+++ b/docs/reference/tmpl/photodb.sgml
@@ -0,0 +1,248 @@
+<!-- ##### SECTION Title ##### -->
+Photo database
+
+<!-- ##### SECTION Short_Description ##### -->
+Functions to create, read, write the photo database
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+These functions are for creating, reading, and writing the photo
+database.
+</para>
+<para>
+Overview of using the Photo database:
+</para>
+<para>
+itdb_photodb_parse():
+Read an existing PhotoDB.
+</para>
+<para>
+itdb_photodb_create():
+Create a new #Itdb_PhotoDB structure. The Photo Library Album is
+(first album) is created automatically.
+</para>
+<para>
+itdb_photodb_add_photo(), itdb_photodb_add_photo_from_data():
+Add a photo to the PhotoDB (from file or from a chunk of
+memory). It is automatically added to the Photo Library Album
+(first album), which is created if it does not exist already.
+</para>
+<para>
+itdb_photodb_photoalbum_create():
+Create and add a new photoalbum.
+</para>
+<para>
+itdb_photodb_photoalbum_add_photo():
+Add a photo (#Itdb_Artwork) to an existing photoalbum.
+</para>
+<para>
+itdb_photodb_photoalbum_remove():
+Remove an existing photoalbum. Pictures can be kept in the
+Photo Library or automatically removed as well.
+</para>
+<para>
+itdb_photodb_remove_photo():
+Remove a photo either from a photoalbum or completely from the database.
+</para>
+<para>
+itdb_photodb_write():
+Write out your PhotoDB.
+</para>
+<para>
+itdb_photodb_free():
+Free all memory taken by the PhotoDB.
+</para>
+<para>
+itdb_photodb_photoalbum_by_name():
+Find the first photoalbum with a given name or the Photo
+Library Album if called with no name.
+</para>
+<para>
+If you cannot add photos because your iPod is not recognized,
+you may have to set the iPod model by calling
+</para>
+<para>
+itdb_device_set_sysinfo (db->device, "ModelNumStr", model);
+</para>
+<para>
+For example, "MA450" would stand for an 80 GB 6th generation iPod Video. See
+<ulink type="http"
+url="http://gtkpod.cvs.sourceforge.net/*checkout*/gtkpod/libgpod/src/itdb_device.c">itdb_device.c</ulink>
+for a list of supported models.
+</para>
+<para>
+This information will be written to the iPod when the PhotoDB is
+saved (itdb_device_write_sysinfo() is called).
+</para>
+<para>
+Have a look at the <ulink type="http"
+url="http://gtkpod.cvs.sourceforge.net/*checkout*/gtkpod/libgpod/tests/test-photos.c">test-photos</ulink>
+test program in the <ulink type="http"
+url="http://gtkpod.cvs.sourceforge.net/gtkpod/libgpod/tests/">tests/</ulink>
+directory of the libgpod source for an example of how to use the interface.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT Itdb_PhotoAlbum ##### -->
+<para>
+
+</para>
+
+@name: 
+@members: 
+@album_type: 
+@playmusic: 
+@repeat: 
+@random: 
+@show_titles: 
+@transition_direction: 
+@slide_duration: 
+@transition_duration: 
+@song_id: 
+@unk024: 
+@unk028: 
+@unk044: 
+@unk048: 
+@album_id: 
+@prev_album_id: 
+@usertype: 
+@userdata: 
+@userdata_duplicate: 
+@userdata_destroy: 
+
+<!-- ##### STRUCT Itdb_PhotoDB ##### -->
+<para>
+
+</para>
+
+@photos: 
+@photoalbums: 
+@device: 
+@usertype: 
+@userdata: 
+@userdata_duplicate: 
+@userdata_destroy: 
+
+<!-- ##### FUNCTION itdb_photodb_add_photo ##### -->
+<para>
+
+</para>
+
+@db: 
+@filename: 
+@position: 
+@rotation: 
+@error: 
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_photodb_add_photo_from_data ##### -->
+<para>
+
+</para>
+
+@db: 
+@image_data: 
+@image_data_len: 
+@position: 
+@rotation: 
+@error: 
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_photodb_create ##### -->
+<para>
+
+</para>
+
+@mountpoint: 
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_photodb_free ##### -->
+<para>
+
+</para>
+
+@photodb: 
+
+
+<!-- ##### FUNCTION itdb_photodb_parse ##### -->
+<para>
+
+</para>
+
+@mp: 
+@error: 
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_photodb_photoalbum_add_photo ##### -->
+<para>
+
+</para>
+
+@db: 
+@album: 
+@photo: 
+@position: 
+
+
+<!-- ##### FUNCTION itdb_photodb_photoalbum_by_name ##### -->
+<para>
+
+</para>
+
+@db: 
+@albumname: 
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_photodb_photoalbum_create ##### -->
+<para>
+
+</para>
+
+@db: 
+@albumname: 
+@pos: 
+@Returns: 
+
+
+<!-- ##### FUNCTION itdb_photodb_photoalbum_remove ##### -->
+<para>
+
+</para>
+
+@db: 
+@album: 
+@remove_pics: 
+
+
+<!-- ##### FUNCTION itdb_photodb_remove_photo ##### -->
+<para>
+
+</para>
+
+@db: 
+@album: 
+@photo: 
+
+
+<!-- ##### FUNCTION itdb_photodb_write ##### -->
+<para>
+
+</para>
+
+@photodb: 
+@error: 
+@Returns: 
+
+
diff --git a/docs/reference/tmpl/track.sgml b/docs/reference/tmpl/track.sgml
index 8ec4980..860c98c 100644
--- a/docs/reference/tmpl/track.sgml
+++ b/docs/reference/tmpl/track.sgml
@@ -227,6 +227,17 @@ information about an iPod track.
 @Returns: 
 
 
+<!-- ##### FUNCTION itdb_track_set_thumbnails_from_data ##### -->
+<para>
+
+</para>
+
+@track: 
+@image_data: 
+@image_data_len: 
+@Returns: 
+
+
 <!-- ##### FUNCTION itdb_track_remove_thumbnails ##### -->
 <para>