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

12 files changed, 575 insertions, 26 deletions

diff --git a/ChangeLog b/ChangeLog
index 6df8c6b..d56e064 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2007-01-11  Todd Zullinger <tmzullinger at users.sourceforge.net>
+
+	* README
+	  docs/reference/libgpod-docs.xml
+	  docs/reference/libgpod-sections.txt
+	  docs/reference/tmpl/artwork.sgml
+	  docs/reference/tmpl/device.sgml
+	  docs/reference/tmpl/itunesdb-db.sgml
+	  docs/reference/tmpl/itunesdb-lowlevel.sgml
+	  docs/reference/tmpl/photodb.sgml
+	  docs/reference/tmpl/track.sgml
+	  src/itdb.h
+	  src/itdb_photoalbum.c: 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.
+
 2007-01-10  Jorg Schuler <jcsjcs at users.sourceforge.net>
 
 	* bindings/python/Makefile.am: correct 'make dist' failure (patch
diff --git a/README b/README
index e899f1d..cfe05f8 100644
--- a/README
+++ b/README
@@ -98,7 +98,7 @@ Quick HOWTO use libgpod for photos
        memory). It is automatically added to the Photo Library Album
        (first album), which is created if it does not exist already.
 
-   itdb_photodb_photoalbum_craete():
+   itdb_photodb_photoalbum_create():
        Create and add a new photoalbum.
 
    itdb_photodb_photoalbum_add_photo():
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>
 
diff --git a/src/itdb.h b/src/itdb.h
index 66bbcac..af728fd 100644
--- a/src/itdb.h
+++ b/src/itdb.h
@@ -1033,7 +1033,7 @@ Itdb_PhotoAlbum *itdb_photodb_photoalbum_create (Itdb_PhotoDB *db,
 						 gint pos);
 Itdb_PhotoDB *itdb_photodb_create (const gchar *mountpoint);
 void itdb_photodb_free (Itdb_PhotoDB *photodb);
-gboolean itdb_photodb_write (Itdb_PhotoDB *db, GError **error);
+gboolean itdb_photodb_write (Itdb_PhotoDB *photodb, GError **error);
 void itdb_photodb_remove_photo (Itdb_PhotoDB *db,
 				Itdb_PhotoAlbum *album,
 				Itdb_Artwork *photo);
diff --git a/src/itdb_photoalbum.c b/src/itdb_photoalbum.c
index 3fd10c7..108ae76 100644
--- a/src/itdb_photoalbum.c
+++ b/src/itdb_photoalbum.c
@@ -51,7 +51,7 @@
        memory). It is automatically added to the Photo Library Album
        (first album), which is created if it does not exist already.
 
-   itdb_photodb_photoalbum_craete():
+   itdb_photodb_photoalbum_create():
        Create and add a new photoalbum.
 
    itdb_photodb_photoalbum_add_photo():
@@ -198,12 +198,11 @@ gchar *itdb_get_photos_thumb_dir (const gchar *mountpoint)
 
 /**
  * itdb_photodb_parse:
- *
- * Parses the photo database of an iPod mounted at @mp.
- *
  * @mp: mountpoint of the iPod
  * @error: will contain the error description when an error occured.
  *
+ * Parses the photo database of an iPod mounted at @mp.
+ *
  * Return value: the imported PhotoDB or NULL in case of an error.
  **/
 Itdb_PhotoDB *itdb_photodb_parse (const gchar *mp, GError **error)
@@ -229,7 +228,6 @@ Itdb_PhotoDB *itdb_photodb_parse (const gchar *mp, GError **error)
 
 /**
  * itdb_photodb_create:
- *
  * @mountpoint: mountpoint or NULL.
  *
  * Creates a new Itdb_PhotoDB. If mountpoint is NULL, you will have to
@@ -582,6 +580,9 @@ void itdb_photodb_remove_photo (Itdb_PhotoDB *db,
  * @albumname: the name of the photoalbum to get or NULL for the
  * master photoalbum.
  *
+ * Find the first photoalbum with a given name or the Photo Library
+ * Album if called with no name.
+ *
  * Return value: a pointer to the first photoalbum named @albumname,
  * else NULL
  */
@@ -603,7 +604,7 @@ Itdb_PhotoAlbum *itdb_photodb_photoalbum_by_name (Itdb_PhotoDB *db, const gchar
 }
 
 /**
- * itdb_photodb_remove_photoalbum:
+ * itdb_photodb_photoalbum_remove:
  * @db: the #Itdb_PhotoDB to apply changes to
  * @album: the album to be removed from the database
  * @remove_pics: TRUE to remove pics in that album permanently from
@@ -670,10 +671,12 @@ void itdb_photodb_photoalbum_add_photo (Itdb_PhotoDB *db,
 /**
  * itdb_photodb_photoalbum_create:
  * @db: The database to create a new album in
- * @album_name: the name of the new album
+ * @albumname: the name of the new album
  * @pos: position where to insert the newly created album (-1 for
  * append to end).
  *
+ * Create and add a new photoalbum.
+ *
  * Return value: the album which was created and added.
  */
 Itdb_PhotoAlbum *itdb_photodb_photoalbum_create (Itdb_PhotoDB *db,