[libmediaart] Documentation fixes

[Sam Thursfield <sthursfield src gnome org>]

commit c1a11f0d4c24a5e6a86e706109654c420d76af9d
Author: Sam Thursfield <sam thursfield codethink co uk>
Date:   Wed Oct 16 20:22:51 2013 +0100

    Documentation fixes

 .../reference/libmediaart/libmediaart-sections.txt |    6 +-
 libmediaart/cache.c                                |   18 +++++-
 libmediaart/extract.c                              |   69 ++++++++++++++++++--
 libmediaart/extract.h                              |    2 +-
 4 files changed, 86 insertions(+), 9 deletions(-)
---
diff --git a/docs/reference/libmediaart/libmediaart-sections.txt 
b/docs/reference/libmediaart/libmediaart-sections.txt
index e92a3cd..cca4ecf 100644
--- a/docs/reference/libmediaart/libmediaart-sections.txt
+++ b/docs/reference/libmediaart/libmediaart-sections.txt
@@ -1,16 +1,18 @@
 <SECTION>
 <FILE>cache</FILE>
+media_art_get_file
 media_art_get_path
-media_art_strip_invalid_entities
 media_art_remove
+media_art_strip_invalid_entities
 </SECTION>
 
 <SECTION>
 <FILE>extract</FILE>
 MediaArtType
 media_art_init
-media_art_process
 media_art_shutdown
+media_art_process_file
+media_art_process
 </SECTION>
 
 <SECTION>
diff --git a/libmediaart/cache.c b/libmediaart/cache.c
index e2592b6..acf187a 100644
--- a/libmediaart/cache.c
+++ b/libmediaart/cache.c
@@ -32,6 +32,19 @@
  * @title: Caching and Management
  * @short_description: Caching and management of stored media art.
  * @include: libmediaart/mediaart.h
+ *
+ * These functions give you access to the media art that has been extracted
+ * and saved in the user's XDG_CACHE_HOME directory.
+ *
+ * To find the media art for a given media file, use the function
+ * media_art_get_file() (you can also use media_art_get_path(), which does the
+ * same thing but for path strings instead of #GFile objects).
+ *
+ * If media art for the file is not found in the cache, these functions will
+ * return %NULL. You may find some embedded media art upon loading the file,
+ * and you can use media_art_process() to convert it to the correct format and
+ * save it in the cache for next time. The media_art_process() function also
+ * supports searching for external media art images using a basic heuristic.
  **/
 
 static gboolean
@@ -78,6 +91,9 @@ media_art_strip_find_next_block (const gchar    *original,
  * media art path with it. Certain characters and charactersets will be stripped
  * and a newly allocated string returned which you must free with g_free().
  *
+ * This functions is used internally by media_art_get_file() and
+ * media_art_get_path(). You will not normally need to call it yourself.
+ *
  * Returns: copy of original but then stripped
  *
  * Since: 0.2.0
@@ -214,7 +230,7 @@ media_art_checksum_for_data (GChecksumType  checksum_type,
  * @local_file will point to a cache file that resides in the same
  * filesystem than @file.
  *
- * When done, both #GFile<!-- -->s must be freed with g_object_unref if
+ * When done, both #GFile<!-- -->s must be freed with g_object_unref() if
  * non-%NULL.
  *
  * Since: 0.2.0
diff --git a/libmediaart/extract.c b/libmediaart/extract.c
index bc157a8..baed4eb 100644
--- a/libmediaart/extract.c
+++ b/libmediaart/extract.c
@@ -41,6 +41,31 @@
  * @title: Extraction
  * @short_description: Extraction of music and movie art.
  * @include: libmediaart/mediaart.h
+ *
+ * The libmediaart library supports taking image data that you have extracted
+ * from a media file and saving it into the media art cache, so that in future
+ * applications can display the media art without having to extract the image
+ * again. This is done using the media_art_process_file() function.
+ *
+ * Extracting the media art from the file needs to be done by your application.
+ * Usually, when an application loads a media file any embedded images will be
+ * made available as a side effect. For example, if you are using GStreamer any
+ * images will be returned through the #GstTagList interface as %GST_TAG_IMAGE
+ * tags.
+ *
+ * The media art cache requires that all images are saved as 'application/jpeg'
+ * files. Embedded images can be in several formats, and
+ * media_art_process_file() will convert the supplied image data into the
+ * correct format if necessary. There are multiple backends that can be used
+ * for this, and you can choose which is used at build time using the library's
+ * 'configure' script.
+ *
+ * If there is no embedded media art in a file, media_art_process_file() will
+ * look in the directory that contains the media file for likely media art
+ * using a simple heuristic.
+ *
+ * You must call media_art_init() before using the functions in libmediaart,
+ * and call media_art_shutdown() to free the resources it uses.
  **/
 
 static const gchar *media_art_type_name[MEDIA_ART_TYPE_COUNT] = {
@@ -934,6 +959,13 @@ media_art_queue_cb (GObject      *source_object,
        file_info_free (fi);
 }
 
+/**
+ * media_art_init:
+ *
+ * Initialise libmediaart.
+ *
+ * Returns: %TRUE if initialisation was successful, %FALSE otherwise.
+ */
 gboolean
 media_art_init (void)
 {
@@ -966,6 +998,11 @@ media_art_init (void)
        return TRUE;
 }
 
+/**
+ * media_art_shutdown:
+ *
+ * Free the image processing backend and other resources used by libmediaart.
+ */
 void
 media_art_shutdown (void)
 {
@@ -1071,17 +1108,24 @@ get_mtime_by_uri (const gchar *uri)
  * @buffer: (allow-none): a buffer containing @file data, or %NULL
  * @len: length of @buffer, or 0
  * @type: The type of media
- * @mime: MIME type of @file, or %NULL
+ * @mime: MIME type of @buffer, or %NULL
  * @artist: The media file artist name, or %NULL
  * @title: The media file title, or %NULL
  * @file: File to be processed
  *
- * Processes a media file, extracting any found media art. If @file
- * is on a removable filesystem, the saved cache file will be local
- * to it.
+ * Processes a media file. If you have extracted any embedded media art and
+ * passed this in as @buffer, the image data will be converted to the correct
+ * format and saved in the media art cache.
+ *
+ * If @buffer is %NULL, libmediaart will search the parent directory of @file
+ * for image files that are likely to be media art for @file, and if one is
+ * found it will be saved in the media art cache.
+ *
+ * If @file is on a removable filesystem, the media art file will be saved in a
+ * cache on the removable file system rather than on the host machine.
  *
  * Returns: #TRUE if the file could be processed.
- **/
+ */
 gboolean
 media_art_process_file (const guchar *buffer,
                        gsize         len,
@@ -1235,6 +1279,21 @@ media_art_process_file (const guchar *buffer,
 }
 
 
+/**
+ * media_art_process:
+ * @buffer: A buffer of binary image data
+ * @len: The length of @buffer, in bytes
+ * @mime: The MIME type of the data stored in @buffer
+ * @type: The type of media that contained the image data
+ * @artist: (allow-none): Artist name of the media
+ * @title: (allow-none): Title of the media
+ * @uri: URI of the media file that contained the image data
+ *
+ * This function is the same as media_art_process_file(), but takes the URI as
+ * a string rather than a #GFile object.
+ *
+ * Returns: %TRUE in case of success, %FALSE otherwise.
+ */
 gboolean
 media_art_process (const unsigned char *buffer,
                    size_t               len,
diff --git a/libmediaart/extract.h b/libmediaart/extract.h
index ff6c3ac..8b521cf 100644
--- a/libmediaart/extract.h
+++ b/libmediaart/extract.h
@@ -60,7 +60,7 @@ gboolean media_art_process  (const unsigned char  *buffer,
 gboolean media_art_process_file (const guchar *buffer,
                                 gsize         len,
                                 MediaArtType  type,
-                                const gchar  *mimetype,
+                                const gchar  *mime,
                                 const gchar  *artist,
                                 const gchar  *title,
                                 GFile        *file);