totem-pl-parser r37 - in trunk: . docs/reference plparse

[pwithnall svn gnome org]

Author: pwithnall
Date: Tue Jan 15 18:47:23 2008
New Revision: 37
URL: http://svn.gnome.org/viewvc/totem-pl-parser?rev=37&view=rev

Log:
2008-01-15  Philip Withnall  <pwithnall svn gnome org>

	* Makefile.am:
	* configure.in:
	* docs/reference/Makefile.am:
	* docs/reference/totem-pl-parser-docs.sgml:
	* docs/reference/totem-pl-parser-sections.txt:
	* docs/reference/totem-pl-parser.types:
	* docs/reference/version.xml.in:
	* plparse/totem-disc.c:
	* plparse/totem-disc.h:
	* plparse/totem-pl-parser.c: (totem_pl_parser_class_init),
	(totem_pl_parser_num_entries):
	* plparse/totem-pl-parser.h: Add full documentation for all
	public symbols exposed by the library, excluding code samples
	for the playlist parser. (Helps: #507995)



Added:
   trunk/docs/reference/totem-pl-parser-docs.sgml
   trunk/docs/reference/totem-pl-parser-sections.txt
   trunk/docs/reference/totem-pl-parser.types
   trunk/docs/reference/version.xml.in   (contents, props changed)
Modified:
   trunk/ChangeLog
   trunk/Makefile.am
   trunk/configure.in
   trunk/docs/reference/Makefile.am
   trunk/plparse/totem-disc.c
   trunk/plparse/totem-disc.h
   trunk/plparse/totem-pl-parser.c
   trunk/plparse/totem-pl-parser.h

Modified: trunk/Makefile.am
==============================================================================
--- trunk/Makefile.am	(original)
+++ trunk/Makefile.am	Tue Jan 15 18:47:23 2008
@@ -19,4 +19,4 @@
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = totem-plparser.pc totem-plparser-mini.pc
 
-DISTCHECK_CONFIGURE_FLAGS = --disable-scrollkeeper
+DISTCHECK_CONFIGURE_FLAGS = --disable-scrollkeeper --enable-gtk-doc

Modified: trunk/configure.in
==============================================================================
--- trunk/configure.in	(original)
+++ trunk/configure.in	Tue Jan 15 18:47:23 2008
@@ -116,6 +116,7 @@
 po/Makefile.in
 docs/Makefile
 docs/reference/Makefile
+docs/reference/version.xml
 ])
 
 AC_MSG_NOTICE([totem-pl-parser was configured with the following options:])

Modified: trunk/docs/reference/Makefile.am
==============================================================================
--- trunk/docs/reference/Makefile.am	(original)
+++ trunk/docs/reference/Makefile.am	Tue Jan 15 18:47:23 2008
@@ -74,7 +74,7 @@
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files=
+content_files=version.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
@@ -94,4 +94,4 @@
 
 # Other files to distribute
 # e.g. EXTRA_DIST += version.xml.in
-EXTRA_DIST += 
+EXTRA_DIST += version.xml.in

Added: trunk/docs/reference/totem-pl-parser-docs.sgml
==============================================================================
--- (empty file)
+++ trunk/docs/reference/totem-pl-parser-docs.sgml	Tue Jan 15 18:47:23 2008
@@ -0,0 +1,19 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
+  <bookinfo>
+    <title>totem-pl-parser Reference Manual</title>
+    <releaseinfo>
+      for totem-pl-parser &version;
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>API Reference</title>
+    <xi:include href="xml/totem-pl-parser.xml"/>
+    <xi:include href="xml/totem-disc.xml"/>
+  </chapter>
+</book>

Added: trunk/docs/reference/totem-pl-parser-sections.txt
==============================================================================
--- (empty file)
+++ trunk/docs/reference/totem-pl-parser-sections.txt	Tue Jan 15 18:47:23 2008
@@ -0,0 +1,70 @@
+<SECTION>
+<FILE>totem-pl-parser</FILE>
+TotemPlParserResult
+TOTEM_PL_PARSER_FIELD_URL
+TOTEM_PL_PARSER_FIELD_GENRE
+TOTEM_PL_PARSER_FIELD_TITLE
+TOTEM_PL_PARSER_FIELD_AUTHOR
+TOTEM_PL_PARSER_FIELD_BASE
+TOTEM_PL_PARSER_FIELD_VOLUME
+TOTEM_PL_PARSER_FIELD_AUTOPLAY
+TOTEM_PL_PARSER_FIELD_DURATION
+TOTEM_PL_PARSER_FIELD_STARTTIME
+TOTEM_PL_PARSER_FIELD_ENDTIME
+TOTEM_PL_PARSER_FIELD_COPYRIGHT
+TOTEM_PL_PARSER_FIELD_ABSTRACT
+TOTEM_PL_PARSER_FIELD_DESCRIPTION
+TOTEM_PL_PARSER_FIELD_SUMMARY
+TOTEM_PL_PARSER_FIELD_MOREINFO
+TOTEM_PL_PARSER_FIELD_SCREENSIZE
+TOTEM_PL_PARSER_FIELD_UI_MODE
+TOTEM_PL_PARSER_FIELD_PUB_DATE
+TOTEM_PL_PARSER_FIELD_FILESIZE
+TOTEM_PL_PARSER_FIELD_LANGUAGE
+TOTEM_PL_PARSER_FIELD_CONTACT
+TOTEM_PL_PARSER_FIELD_IMAGE_URL
+TOTEM_PL_PARSER_FIELD_IS_PLAYLIST
+TotemPlParserType
+TotemPlParserError
+TotemPlParserIterFunc
+totem_pl_parser_parse_duration
+totem_pl_parser_parse_date
+totem_pl_parser_resolve_url
+totem_pl_parser_write
+totem_pl_parser_write_with_title
+totem_pl_parser_add_ignored_scheme
+totem_pl_parser_add_ignored_mimetype
+totem_pl_parser_parse
+totem_pl_parser_parse_with_base
+totem_pl_parser_new
+<SUBSECTION Standard>
+TOTEM_PL_PARSER
+TOTEM_IS_PL_PARSER
+TOTEM_TYPE_PL_PARSER
+totem_pl_parser_get_type
+TOTEM_PL_PARSER_CLASS
+TOTEM_IS_PL_PARSER_CLASS
+totem_pl_parser_error_quark
+TOTEM_PL_PARSER_ERROR
+<SUBSECTION Private>
+TotemPlParser
+TotemPlParserClass
+TotemPlParserPrivate
+entry_parsed
+playlist_started
+playlist_ended
+</SECTION>
+
+<SECTION>
+<FILE>totem-disc</FILE>
+TotemDiscMediaType
+totem_cd_detect_type
+totem_cd_detect_type_with_url
+totem_cd_detect_type_from_dir
+totem_cd_get_human_readable_name
+totem_cd_mrl_from_type
+totem_cd_has_medium
+<SUBSECTION Standard>
+MediaType
+</SECTION>
+

Added: trunk/docs/reference/totem-pl-parser.types
==============================================================================
--- (empty file)
+++ trunk/docs/reference/totem-pl-parser.types	Tue Jan 15 18:47:23 2008
@@ -0,0 +1 @@
+totem_pl_parser_get_type

Added: trunk/docs/reference/version.xml.in
==============================================================================
--- (empty file)
+++ trunk/docs/reference/version.xml.in	Tue Jan 15 18:47:23 2008
@@ -0,0 +1 @@
+ TOTEM_PL_PARSER_VERSION_MAJOR@  TOTEM_PL_PARSER_VERSION_MINOR@  TOTEM_PL_PARSER_VERSION_MICRO@

Modified: trunk/plparse/totem-disc.c
==============================================================================
--- trunk/plparse/totem-disc.c	(original)
+++ trunk/plparse/totem-disc.c	Tue Jan 15 18:47:23 2008
@@ -27,6 +27,16 @@
  *
  */
 
+/**
+ * SECTION:totem-disc
+ * @short_description: disc utility functions
+ * @stability: Stable
+ * @include: totem-disc.h
+ *
+ * This file has various different disc utility functions for getting
+ * the media types and labels of discs.
+ **/
+
 #include "config.h"
 
 #include <fcntl.h>
@@ -685,6 +695,17 @@
   return MEDIA_TYPE_DATA;
 }
 
+/**
+ * totem_cd_mrl_from_type:
+ * @scheme: a scheme (e.g. "dvd")
+ * @dir: a directory URI
+ *
+ * Builds an MRL using the scheme @scheme and the given URI @dir,
+ * taking the filename from the URI if it's a <filename>file://</filename> and just
+ * using the whole URI otherwise.
+ *
+ * Return value: a newly-allocated string containing the MRL
+ **/
 char *
 totem_cd_mrl_from_type (const char *scheme, const char *dir)
 {
@@ -720,6 +741,18 @@
     return parent;
 }
 
+/**
+ * totem_cd_detect_type_from_dir:
+ * @dir: a directory URI
+ * @url: return location for the disc's MRL, or %NULL
+ * @error: return location for a #GError, or %NULL
+ *
+ * Detects the disc's type, given its mount directory URI. If
+ * a string pointer is passed to @url, it will return the disc's
+ * MRL as from totem_cd_mrl_from_type().
+ *
+ * Return value: #TotemDiscMediaType corresponding to the disc's type, or #MEDIA_TYPE_ERROR on failure
+ **/
 TotemDiscMediaType
 totem_cd_detect_type_from_dir (const char *dir, char **url, GError **error)
 {
@@ -771,6 +804,18 @@
   return type;
 }
 
+/**
+ * totem_cd_detect_type_with_url:
+ * @device: a device node path
+ * @url: return location for the disc's MRL, or %NULL
+ * @error: return location for a #GError, or %NULL
+ *
+ * Detects the disc's type, given its device node path. If
+ * a string pointer is passed to @url, it will return the disc's
+ * MRL as from totem_cd_mrl_from_type().
+ *
+ * Return value: #TotemDiscMediaType corresponding to the disc's type, or #MEDIA_TYPE_ERROR on failure
+ **/
 TotemDiscMediaType
 totem_cd_detect_type_with_url (const char *device,
     			       char      **url,
@@ -827,6 +872,15 @@
   return type;
 }
 
+/**
+ * totem_cd_detect_type:
+ * @device: a device node path
+ * @error: return location for a #GError, or %NULL
+ *
+ * Detects the disc's type, given its device node path.
+ *
+ * Return value: #TotemDiscMediaType corresponding to the disc's type, or #MEDIA_TYPE_ERROR on failure
+ **/
 TotemDiscMediaType
 totem_cd_detect_type (const char  *device,
 		      GError     **error)
@@ -834,6 +888,14 @@
   return totem_cd_detect_type_with_url (device, NULL, error);
 }
 
+/**
+ * totem_cd_has_medium:
+ * @device: a device node path
+ *
+ * Returns whether the disc has a physical medium.
+ *
+ * Return value: %TRUE if the disc physically exists
+ **/
 gboolean
 totem_cd_has_medium (const char *device)
 {
@@ -849,6 +911,15 @@
   return retval;
 }
 
+/**
+ * totem_cd_get_human_readable_name:
+ * @type: a #TotemDiscMediaType
+ *
+ * Returns the human-readable name for the given
+ * #TotemDiscMediaType.
+ *
+ * Return value: the disc media type's readable name, which must not be freed, or %NULL for unhandled media types
+ **/
 const char *
 totem_cd_get_human_readable_name (TotemDiscMediaType type)
 {

Modified: trunk/plparse/totem-disc.h
==============================================================================
--- trunk/plparse/totem-disc.h	(original)
+++ trunk/plparse/totem-disc.h	Tue Jan 15 18:47:23 2008
@@ -26,8 +26,21 @@
 
 G_BEGIN_DECLS
 
+/**
+ * TotemDiscMediaType:
+ * @MEDIA_TYPE_ERROR: there was an error determining the media's type
+ * @MEDIA_TYPE_DATA: data disc
+ * @MEDIA_TYPE_CDDA: audio CD
+ * @MEDIA_TYPE_VCD: video CD
+ * @MEDIA_TYPE_DVD: video DVD
+ * @MEDIA_TYPE_DVB: digital television
+ * @MEDIA_TYPE_NUM_TYPES: the number of supported media types
+ *
+ * Gives the media type of a disc, or %MEDIA_TYPE_ERROR if the media type
+ * could not be determined.
+ **/
 typedef enum {
-  MEDIA_TYPE_ERROR = -1, /* error */
+  MEDIA_TYPE_ERROR = -1,
   MEDIA_TYPE_DATA = 1,
   MEDIA_TYPE_CDDA,
   MEDIA_TYPE_VCD,

Modified: trunk/plparse/totem-pl-parser.c
==============================================================================
--- trunk/plparse/totem-pl-parser.c	(original)
+++ trunk/plparse/totem-pl-parser.c	Tue Jan 15 18:47:23 2008
@@ -18,9 +18,18 @@
    Boston, MA 02111-1307, USA.
 
    Authors: Bastien Nocera <hadess hadess net>
-
  */
 
+/**
+ * SECTION:totem-pl-parser
+ * @short_description: playlist parser
+ * @stability: Stable
+ * @include: totem-pl-parser.h
+ *
+ * #TotemPlParser is a general-purpose playlist parser and writer, with
+ * support for several different types of playlist.
+ **/
+
 #include "config.h"
 
 #include <string.h>
@@ -158,6 +167,13 @@
 	object_class->get_property = totem_pl_parser_get_property;
 
 	/* Properties */
+
+	/**
+	 * TotemPlParser:recurse:
+	 *
+	 * If %TRUE, the parser will recursively fetch playlists linked to by
+	 * the current one.
+	 **/
 	g_object_class_install_property (object_class,
 					 PROP_RECURSE,
 					 g_param_spec_boolean ("recurse",
@@ -166,6 +182,11 @@
 							       TRUE,
 							       G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 
+	/**
+	 * TotemPlParser:debug:
+	 *
+	 * If %TRUE, the parser will output debug information.
+	 **/
 	g_object_class_install_property (object_class,
 					 PROP_DEBUG,
 					 g_param_spec_boolean ("debug",
@@ -174,6 +195,12 @@
 							       FALSE,
 							       G_PARAM_READWRITE));
 
+	/**
+	 * TotemPlParser:force:
+	 *
+	 * If %TRUE, the parser will attempt to parse a playlist, even if it
+	 * appears to be unsupported (usually because of its filename extension).
+	 **/
 	g_object_class_install_property (object_class,
 					 PROP_FORCE,
 					 g_param_spec_boolean ("force",
@@ -182,6 +209,13 @@
 							       FALSE,
 							       G_PARAM_READWRITE));
 
+	/**
+	 * TotemPlParser:disable-unsafe:
+	 *
+	 * If %TRUE, the parser will not parse unsafe locations, such as local devices
+	 * and local files if the playlist isn't local. This is useful if the library
+	 * is parsing a playlist from a remote location such as a website.
+	 **/
 	g_object_class_install_property (object_class,
 					 PROP_DISABLE_UNSAFE,
 					 g_param_spec_boolean ("disable-unsafe",
@@ -430,7 +464,7 @@
 }
 
 /**
- * totem_pl_parser_new
+ * totem_pl_parser_new:
  *
  * Creates a #TotemPlParser object.
  *
@@ -443,6 +477,14 @@
 	return TOTEM_PL_PARSER (g_object_new (TOTEM_TYPE_PL_PARSER, NULL));
 }
 
+/**
+ * totem_pl_parser_playlist_end:
+ * @parser: a #TotemPlParser
+ * @playlist_uri: the playlist URI
+ *
+ * Emits the #TotemPlParser::playlist-ended signal on @parser for
+ * the playlist @playlist_uri.
+ **/
 void
 totem_pl_parser_playlist_end (TotemPlParser *parser, const char *playlist_uri)
 {
@@ -544,6 +586,14 @@
 	return g_strdup (mimetype);
 }
 
+/**
+ * totem_pl_parser_base_url:
+ * @url: a URI
+ *
+ * Returns the parent URI of @url.
+ *
+ * Return value: a newly-allocated string containing @url's parent URI, or %NULL
+ **/
 char *
 totem_pl_parser_base_url (const char *url)
 {
@@ -569,6 +619,15 @@
 	return base;
 }
 
+/**
+ * totem_pl_parser_line_is_empty:
+ * @line: a playlist line to check
+ *
+ * Checks to see if the given string line is empty or %NULL,
+ * counting tabs and spaces, but not newlines, as "empty".
+ *
+ * Return value: %TRUE if @line is empty
+ **/
 gboolean
 totem_pl_parser_line_is_empty (const char *line)
 {
@@ -584,6 +643,16 @@
 	return TRUE;
 }
 
+/**
+ * totem_pl_parser_write_string:
+ * @handle: a #GnomeVFSHandle to an open file
+ * @buf: the string buffer to write out
+ * @error: return location for a #GError, or %NULL
+ *
+ * Writes the string @buf out to the file specified by @handle.
+ *
+ * Return value: %TRUE on success
+ **/
 gboolean
 totem_pl_parser_write_string (GnomeVFSHandle *handle, const char *buf, GError **error)
 {
@@ -593,6 +662,17 @@
 	return totem_pl_parser_write_buffer (handle, buf, len, error);
 }
 
+/**
+ * totem_pl_parser_write_buffer:
+ * @handle: a #GnomeVFSHandle to an open file
+ * @buf: the string buffer to write out
+ * @len: the length of the string to write out
+ * @error: return location for a #GError, or %NULL
+ *
+ * Writes @len bytes of @buf to the file specified by @handle.
+ *
+ * Return value: %TRUE on success
+ **/
 gboolean
 totem_pl_parser_write_buffer (GnomeVFSHandle *handle, const char *buf, guint len, GError **error)
 {
@@ -613,6 +693,18 @@
 	return TRUE;
 }
 
+/**
+ * totem_pl_parser_num_entries:
+ * @parser: a #TotemPlParser
+ * @model: a #GtkTreeModel
+ * @func: a pointer to a #TotemPlParserIterFunc callback function
+ * @user_data: a pointer to be passed to each call of @func
+ *
+ * Returns the number of entries in @parser's playlist, and calls
+ * @func for each valid entry in the playlist.
+ *
+ * Return value: the number of entries in the playlist
+ **/
 int
 totem_pl_parser_num_entries (TotemPlParser *parser, GtkTreeModel *model,
 			     TotemPlParserIterFunc func, gpointer user_data)
@@ -628,7 +720,7 @@
 		char *url, *title;
 		gboolean custom_title;
 
-		if (gtk_tree_model_iter_nth_child (model, &iter, NULL, i -1) == FALSE)
+		if (gtk_tree_model_iter_nth_child (model, &iter, NULL, i - 1) == FALSE)
 			return i - ignored;
 
 		func (model, &iter, &url, &title, &custom_title, user_data);
@@ -642,6 +734,19 @@
 	return num_entries - ignored;
 }
 
+/**
+ * totem_pl_parser_relative:
+ * @url: a URI
+ * @output: a base path and filename
+ *
+ * Returns the URI of @url relative to @output if possible, and %NULL
+ * if not.
+ *
+ * <emphasis>See totem_pl_parser_resolve_url() to convert from relative URLs
+ * to absolute URLs.</emphasis>
+ *
+ * Return value: a newly-allocated relative URI string, or %NULL
+ **/
 char *
 totem_pl_parser_relative (const char *url, const char *output)
 {
@@ -688,6 +793,27 @@
 }
 
 #ifndef TOTEM_PL_PARSER_MINI
+/**
+ * totem_pl_parser_write_with_title:
+ * @parser: a #TotemPlParser
+ * @model: a #GtkTreeModel
+ * @func: a pointer to a #TotemPlParserIterFunc callback function
+ * @output: the output path and filename
+ * @title: the playlist title
+ * @type: a #TotemPlParserType for the ouputted playlist
+ * @user_data: a pointer to be passed to each call of @func
+ * @error: return location for a #GError, or %NULL
+ *
+ * Writes the playlist held by @parser and @model out to the file of
+ * path @output. The playlist is written in the format @type and is
+ * given the title @title.
+ *
+ * For each entry in the @model, the function @func is called (and passed
+ * @user_data), which gets various metadata values about the entry for
+ * the playlist writer.
+ *
+ * Return value: %TRUE on success
+ **/
 gboolean
 totem_pl_parser_write_with_title (TotemPlParser *parser, GtkTreeModel *model,
 				  TotemPlParserIterFunc func,
@@ -718,6 +844,26 @@
 	return FALSE;
 }
 
+/**
+ * totem_pl_parser_write:
+ * @parser: a #TotemPlParser
+ * @model: a #GtkTreeModel
+ * @func: a pointer to a #TotemPlParserIterFunc callback function
+ * @output: the output path and filename
+ * @type: a #TotemPlParserType for the ouputted playlist
+ * @user_data: a pointer to be passed to each call of @func
+ * @error: return location for a #GError, or %NULL
+ *
+ * Writes the playlist held by @parser and @model out to the file of
+ * path @output. The playlist is written in the format @type and is given
+ * a %NULL title.
+ *
+ * For each entry in the @model, the function @func is called (and passed
+ * @user_data), which gets various metadata values about the entry for
+ * the playlist writer.
+ *
+ * Return value: %TRUE on success
+ **/
 gboolean
 totem_pl_parser_write (TotemPlParser *parser, GtkTreeModel *model,
 		       TotemPlParserIterFunc func,
@@ -731,6 +877,16 @@
 
 #endif /* TOTEM_PL_PARSER_MINI */
 
+/**
+ * totem_pl_parser_read_ini_line_int:
+ * @lines: a NULL-terminated array of INI lines to read
+ * @key: the key to match
+ *
+ * Returns the first integer value case-insensitively matching the specified
+ * key as an integer. The parser ignores leading whitespace on lines.
+ *
+ * Return value: the integer value, or -1 on error
+ **/
 int
 totem_pl_parser_read_ini_line_int (char **lines, const char *key)
 {
@@ -763,6 +919,19 @@
 	return retval;
 }
 
+/**
+ * totem_pl_parser_read_ini_line_string_with_sep:
+ * @lines: a NULL-terminated array of INI lines to read
+ * @key: the key to match
+ * @dos_mode: %TRUE if the returned string should end in \r\0, instead of \n\0
+ * @sep: the key-value separator
+ *
+ * Returns the first string value case-insensitively matching the specified
+ * key, where the two are separated by @sep. The parser ignores leading whitespace
+ * on lines.
+ *
+ * Return value: a newly-allocated string value, or %NULL
+ **/
 char*
 totem_pl_parser_read_ini_line_string_with_sep (char **lines, const char *key,
 		gboolean dos_mode, const char *sep)
@@ -803,6 +972,17 @@
 	return retval;
 }
 
+/**
+ * totem_pl_parser_read_ini_line_string:
+ * @lines: a NULL-terminated array of INI lines to read
+ * @key: the key to match
+ * @dos_mode: %TRUE if the returned string should end in \r\0, instead of \n\0
+ *
+ * Returns the first string value case-insensitively matching the
+ * specified key. The parser ignores leading whitespace on lines.
+ *
+ * Return value: a newly-allocated string value, or %NULL
+ **/
 char*
 totem_pl_parser_read_ini_line_string (char **lines, const char *key, gboolean dos_mode)
 {
@@ -929,6 +1109,16 @@
 	g_object_unref (G_OBJECT (parser));
 }
 
+/**
+ * totem_pl_parser_add_url:
+ * @parser: a #TotemPlParser
+ * @first_property_name: the first property name
+ * @Varargs: value for the first property, followed optionally by more
+ * name/value pairs, followed by %NULL
+ *
+ * Adds a URL to the playlist with the properties given in @first_property_name
+ * and @Varargs.
+ **/
 void
 totem_pl_parser_add_url (TotemPlParser *parser,
 			 const char *first_property_name,
@@ -940,6 +1130,14 @@
 	va_end (var_args);
 }
 
+/**
+ * totem_pl_parser_add_one_url:
+ * @parser: a #TotemPlParser
+ * @url: the entry's URL
+ * @title: the entry's title
+ *
+ * Adds a single URL entry with only URL and title strings to the playlist.
+ **/
 void
 totem_pl_parser_add_one_url (TotemPlParser *parser, const char *url, const char *title)
 {
@@ -977,6 +1175,19 @@
 	return TRUE;
 }
 
+/**
+ * totem_pl_parser_resolve_url:
+ * @base: a base path and filename
+ * @url: a URI
+ *
+ * Returns the absolute URI of @url, resolving any relative
+ * paths with respect to @base.
+ *
+ * <emphasis>See totem_pl_parser_relative() to convert from absolute URLs
+ * to relative URLs.</emphasis>
+ *
+ * Return value: a newly-allocated resolved URL
+ **/
 char *
 totem_pl_parser_resolve_url (const char *base, const char *url)
 {
@@ -1094,6 +1305,16 @@
 	PLAYLIST_TYPE3 ("application/x-trash"),
 };
 
+/**
+ * totem_pl_parser_scheme_is_ignored:
+ * @parser: a #TotemPlParser
+ * @url: a URL
+ *
+ * Checks to see if @url's scheme is in the @parser's list of
+ * schemes to ignore.
+ *
+ * Return value: %TRUE if @url's scheme is ignored
+ **/
 gboolean
 totem_pl_parser_scheme_is_ignored (TotemPlParser *parser, const char *url)
 {
@@ -1133,6 +1354,23 @@
 
 }
 
+/**
+ * totem_pl_parser_ignore:
+ * @parser: a #TotemPlParser
+ * @url: a URL
+ *
+ * Checks if the URL should be ignored. URLs are <emphasis>not</emphasis> ignored if:
+ * <itemizedlist>
+ *  <listitem><para>they have an unknown mimetype,</para></listitem>
+ *  <listitem><para>they have a special mimetype,</para></listitem>
+ *  <listitem><para>they have a mimetype which could be a video or a playlist.</para></listitem>
+ * </itemizedlist>
+ *
+ * URLs are automatically ignored if their scheme is ignored as per totem_pl_parser_scheme_is_ignored(),
+ * and are ignored if all the other tests are inconclusive.
+ *
+ * Return value: %TRUE if @url is to be ignored
+ **/
 gboolean
 totem_pl_parser_ignore (TotemPlParser *parser, const char *url)
 {
@@ -1318,6 +1556,19 @@
 	return ret;
 }
 
+/**
+ * totem_pl_parser_parse_with_base:
+ * @parser: a #TotemPlParser
+ * @url: the URL of the playlist to parse
+ * @base: the base path for relative filenames
+ * @fallback: %TRUE if the parser should add the playlist URL to the
+ * end of the playlist on parse failure
+ *
+ * Parses a playlist given by the absolute URL @url, using
+ * @base to resolve relative paths where appropriate.
+ *
+ * Return value: a #TotemPlParserResult
+ **/
 TotemPlParserResult
 totem_pl_parser_parse_with_base (TotemPlParser *parser, const char *url,
 				 const char *base, gboolean fallback)
@@ -1336,6 +1587,17 @@
 	return totem_pl_parser_parse_internal (parser, url, base);
 }
 
+/**
+ * totem_pl_parser_parse:
+ * @parser: a #TotemPlParser
+ * @url: the URL of the playlist to parse
+ * @fallback: %TRUE if the parser should add the playlist URL to the
+ * end of the playlist on parse failure
+ *
+ * Parses a playlist given by the absolute URL @url.
+ *
+ * Return value: a #TotemPlParserResult
+ **/
 TotemPlParserResult
 totem_pl_parser_parse (TotemPlParser *parser, const char *url,
 		       gboolean fallback)
@@ -1343,6 +1605,14 @@
 	return totem_pl_parser_parse_with_base (parser, url, NULL, fallback);
 }
 
+/**
+ * totem_pl_parser_add_ignored_scheme:
+ * @parser: a #TotemPlParser
+ * @scheme: the scheme to ignore
+ *
+ * Adds a scheme to the list of schemes to ignore, so that
+ * any URL using that scheme is ignored during playlist parsing.
+ **/
 void
 totem_pl_parser_add_ignored_scheme (TotemPlParser *parser,
 		const char *scheme)
@@ -1353,6 +1623,14 @@
 		(parser->priv->ignore_schemes, g_strdup (scheme));
 }
 
+/**
+ * totem_pl_parser_add_ignored_mimetype:
+ * @parser: a #TotemPlParser
+ * @mimetype: the mimetype to ignore
+ *
+ * Adds a mimetype to the list of mimetypes to ignore, so that
+ * any URL of that mimetype is ignored during playlist parsing.
+ **/
 void
 totem_pl_parser_add_ignored_mimetype (TotemPlParser *parser,
 		const char *mimetype)
@@ -1363,6 +1641,16 @@
 		(parser->priv->ignore_mimetypes, g_strdup (mimetype));
 }
 
+/**
+ * totem_pl_parser_parse_duration:
+ * @duration: the duration string to parse
+ * @debug: %TRUE if debug statements should be printed
+ *
+ * Parses the given duration string and returns it as a <type>gint64</type>
+ * denoting the duration in seconds.
+ *
+ * Return value: the duration in seconds, or -1 on error
+ **/
 gint64
 totem_pl_parser_parse_duration (const char *duration, gboolean debug)
 {
@@ -1428,6 +1716,16 @@
 	return TRUE;
 }
 
+/**
+ * totem_pl_parser_parse_date:
+ * @date_str: the date string to parse
+ * @debug: %TRUE if debug statements should be printed
+ *
+ * Parses the given date string and returns it as a <type>gint64</type>
+ * denoting the date in seconds since the UNIX Epoch.
+ *
+ * Return value: the date in seconds, or -1 on error
+ **/
 guint64
 totem_pl_parser_parse_date (const char *date_str, gboolean debug)
 {
@@ -1450,6 +1748,17 @@
 
 #endif /* !TOTEM_PL_PARSER_MINI */
 
+/**
+ * totem_pl_parser_can_parse_from_data:
+ * @data: the data to check for parsability
+ * @len: the length of data to check
+ * @debug: %TRUE if debug statements should be printed
+ *
+ * Checks if the first @len bytes of @data can be parsed, using the same checks
+ * and precedences as totem_pl_parser_ignore().
+ *
+ * Return value: %TRUE if @data can be parsed
+ **/
 gboolean
 totem_pl_parser_can_parse_from_data (const char *data,
 				     gsize len,
@@ -1493,6 +1802,16 @@
 	return FALSE;
 }
 
+/**
+ * totem_pl_parser_can_parse_from_filename:
+ * @filename: the file to check for parsability
+ * @debug: %TRUE if debug statements should be printed
+ *
+ * Checks if the file can be parsed, using the same checks and precedences
+ * as totem_pl_parser_ignore().
+ *
+ * Return value: %TRUE if @filename can be parsed
+ **/
 gboolean
 totem_pl_parser_can_parse_from_filename (const char *filename, gboolean debug)
 {

Modified: trunk/plparse/totem-pl-parser.h
==============================================================================
--- trunk/plparse/totem-pl-parser.h	(original)
+++ trunk/plparse/totem-pl-parser.h	Tue Jan 15 18:47:23 2008
@@ -37,6 +37,15 @@
 #define TOTEM_IS_PL_PARSER(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), TOTEM_TYPE_PL_PARSER))
 #define TOTEM_IS_PL_PARSER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), TOTEM_TYPE_PL_PARSER))
 
+/**
+ * TotemPlParserResult:
+ * @TOTEM_PL_PARSER_RESULT_UNHANDLED: The playlist could not be handled.
+ * @TOTEM_PL_PARSER_RESULT_ERROR: There was an error parsing the playlist.
+ * @TOTEM_PL_PARSER_RESULT_SUCCESS: The playlist was parsed successfully.
+ * @TOTEM_PL_PARSER_RESULT_IGNORED: The playlist was ignored due to its scheme or MIME type (see totem_pl_parser_add_ignored_scheme() and totem_pl_parser_add_ignored_mimetype()).
+ *
+ * Gives the result of parsing a playlist.
+ **/
 typedef enum
 {
 	TOTEM_PL_PARSER_RESULT_UNHANDLED,
@@ -55,29 +64,146 @@
 };
 
 /* Known metadata fields */
+
+/**
+ * TOTEM_PL_PARSER_FIELD_URL:
+ *
+ * Metadata field for an entry's URL.
+ **/
 #define TOTEM_PL_PARSER_FIELD_URL		"url"
+/**
+ * TOTEM_PL_PARSER_FIELD_GENRE:
+ *
+ * Metadata field for an entry's genre.
+ **/
 #define TOTEM_PL_PARSER_FIELD_GENRE		"genre"
+/**
+ * TOTEM_PL_PARSER_FIELD_TITLE:
+ *
+ * Metadata field for an entry's displayable title.
+ **/
 #define TOTEM_PL_PARSER_FIELD_TITLE		"title"
+/**
+ * TOTEM_PL_PARSER_FIELD_AUTHOR:
+ *
+ * Metadata field for an entry's author/composer/director.
+ **/
 #define TOTEM_PL_PARSER_FIELD_AUTHOR		"author"
+/**
+ * TOTEM_PL_PARSER_FIELD_BASE:
+ *
+ * Metadata field for an entry's base path.
+ **/
 #define TOTEM_PL_PARSER_FIELD_BASE		"base"
+/**
+ * TOTEM_PL_PARSER_FIELD_VOLUME:
+ *
+ * Metadata field for an entry's playback volume.
+ **/
 #define TOTEM_PL_PARSER_FIELD_VOLUME		"volume"
+/**
+ * TOTEM_PL_PARSER_FIELD_AUTOPLAY:
+ *
+ * Metadata field for an entry's "autoplay" flag, which is %TRUE if the entry should play automatically.
+ **/
 #define TOTEM_PL_PARSER_FIELD_AUTOPLAY		"autoplay"
+/**
+ * TOTEM_PL_PARSER_FIELD_DURATION:
+ *
+ * Metadata field for an entry's playback duration, which should be parsed using totem_pl_parser_parse_duration().
+ **/
 #define TOTEM_PL_PARSER_FIELD_DURATION		"duration"
+/**
+ * TOTEM_PL_PARSER_FIELD_STARTTIME:
+ *
+ * Metadata field for an entry's playback start time, which should be parsed using totem_pl_parser_parse_duration().
+ **/
 #define TOTEM_PL_PARSER_FIELD_STARTTIME		"starttime"
+/**
+ * TOTEM_PL_PARSER_FIELD_ENDTIME:
+ *
+ * Metadata field for an entry's playback end time.
+ **/
 #define TOTEM_PL_PARSER_FIELD_ENDTIME		"endtime"
+/**
+ * TOTEM_PL_PARSER_FIELD_COPYRIGHT:
+ *
+ * Metadata field for an entry's copyright line.
+ **/
 #define TOTEM_PL_PARSER_FIELD_COPYRIGHT		"copyright"
+/**
+ * TOTEM_PL_PARSER_FIELD_ABSTRACT:
+ *
+ * Metadata field for an entry's abstract text.
+ **/
 #define TOTEM_PL_PARSER_FIELD_ABSTRACT		"abstract"
+/**
+ * TOTEM_PL_PARSER_FIELD_DESCRIPTION:
+ *
+ * Metadata field for an entry's description.
+ **/
 #define TOTEM_PL_PARSER_FIELD_DESCRIPTION	"description"
+/**
+ * TOTEM_PL_PARSER_FIELD_SUMMARY:
+ *
+ * Metadata field for an entry's summary. (In practice, identical to %TOTEM_PL_PARSER_FIELD_DESCRIPTION.)
+ **/
 #define TOTEM_PL_PARSER_FIELD_SUMMARY		TOTEM_PL_PARSER_FIELD_DESCRIPTION
+/**
+ * TOTEM_PL_PARSER_FIELD_MOREINFO:
+ *
+ * Metadata field for an entry's "more info" URL.
+ **/
 #define TOTEM_PL_PARSER_FIELD_MOREINFO		"moreinfo"
+/**
+ * TOTEM_PL_PARSER_FIELD_SCREENSIZE:
+ *
+ * Metadata field for an entry's preferred screen size.
+ **/
 #define TOTEM_PL_PARSER_FIELD_SCREENSIZE	"screensize"
+/**
+ * TOTEM_PL_PARSER_FIELD_UI_MODE:
+ *
+ * Metadata field for an entry's preferred UI mode.
+ **/
 #define TOTEM_PL_PARSER_FIELD_UI_MODE		"ui-mode"
+/**
+ * TOTEM_PL_PARSER_FIELD_PUB_DATE:
+ *
+ * Metadata field for an entry's publication date, which should be parsed using totem_pl_parser_parse_date().
+ **/
 #define TOTEM_PL_PARSER_FIELD_PUB_DATE		"publication-date"
+/**
+ * TOTEM_PL_PARSER_FIELD_FILESIZE:
+ *
+ * Metadata field for an entry's filesize in bytes. This is only advisory, and can sometimes not match the actual filesize of the stream.
+ **/
 #define TOTEM_PL_PARSER_FIELD_FILESIZE		"filesize"
+/**
+ * TOTEM_PL_PARSER_FIELD_LANGUAGE:
+ *
+ * Metadata field for an entry's audio language.
+ **/
 #define TOTEM_PL_PARSER_FIELD_LANGUAGE		"language"
+/**
+ * TOTEM_PL_PARSER_FIELD_CONTACT:
+ *
+ * Metadata field for an entry's contact details for the webmaster.
+ **/
 #define TOTEM_PL_PARSER_FIELD_CONTACT		"contact"
+/**
+ * TOTEM_PL_PARSER_FIELD_IMAGE_URL:
+ *
+ * Metadata field for an entry's thumbnail image URL.
+ **/
 #define TOTEM_PL_PARSER_FIELD_IMAGE_URL		"image-url"
-
+/**
+ * TOTEM_PL_PARSER_FIELD_IS_PLAYLIST:
+ *
+ * Metadata field used to tell the calling code that the parsing of a playlist
+ * started. It is only %TRUE for the metadata passed to #TotemPlParser::playlist-started or
+ * #TotemPlParser::playlist-ended signal handlers.
+ **/
 #define TOTEM_PL_PARSER_FIELD_IS_PLAYLIST	"is-playlist"
 
 struct TotemPlParserClass {
@@ -94,6 +220,16 @@
 				const char *uri);
 };
 
+/**
+ * TotemPlParserType:
+ * @TOTEM_PL_PARSER_PLS: PLS parser
+ * @TOTEM_PL_PARSER_M3U: M3U parser
+ * @TOTEM_PL_PARSER_M3U_DOS: M3U (DOS linebreaks) parser
+ * @TOTEM_PL_PARSER_XSPF: XSPF parser
+ * @TOTEM_PL_PARSER_IRIVER_PLA: iRiver PLA parser
+ *
+ * The type of playlist a #TotemPlParser will parse.
+ **/
 typedef enum
 {
 	TOTEM_PL_PARSER_PLS,
@@ -103,6 +239,14 @@
 	TOTEM_PL_PARSER_IRIVER_PLA,
 } TotemPlParserType;
 
+/**
+ * TotemPlParserError:
+ * @TOTEM_PL_PARSER_ERROR_VFS_OPEN: Error on opening a file
+ * @TOTEM_PL_PARSER_ERROR_VFS_WRITE: Error on writing a file
+ *
+ * Allows you to differentiate between different
+ * errors occurring during file operations in a #TotemPlParser.
+ **/
 typedef enum
 {
 	TOTEM_PL_PARSER_ERROR_VFS_OPEN,
@@ -113,6 +257,21 @@
 
 GQuark totem_pl_parser_error_quark (void);
 
+/**
+ * TotemPlParserIterFunc:
+ * @model: a #GtkTreeModel containing the playlist entries
+ * @iter: a #GtkTreeIter pointing to the current row
+ * @uri: return location for the entry's URI, or %NULL
+ * @title: return location for the entry's title, or %NULL
+ * @custom_title: return location for a boolean which, if %TRUE, indicates that the entry's @title is custom; or %NULL
+ * @user_data: user data to pass to the function
+ *
+ * Functions such as totem_pl_parser_write() accept pointers to TotemPlParserIterFunc()s
+ * as callbacks to call for each entry in the playlist. These functions
+ * are specific to each use of the playlist API, and should set the entry's
+ * @uri, @title and @custom_title return values, getting the data from @model
+ * or otherwise.
+ **/
 typedef void (*TotemPlParserIterFunc) (GtkTreeModel *model, GtkTreeIter *iter,
 				       char **uri, char **title,
 				       gboolean *custom_title,