Tidy up the documentation a bit, taking advantage of recent gtk-doc

2009-02-07  Philip Withnall  <philip@tecnocode.co.uk>

	* configure.in:
	* docs/reference/Makefile.am:
	* docs/reference/totem-pl-parser-docs.sgml:
	* docs/reference/totem-pl-parser-docs.xml:
	* docs/reference/totem-pl-parser-sections.txt:
	* plparse/totem-disc.c:
	* plparse/totem-pl-parser.c:
	* plparse/totem-pl-parser.h: Tidy up the documentation a bit, taking
	advantage of recent gtk-doc features, and also adding missing "since"
	and "deprecated" tags to a few symbols. gtkdoc-check will now run on
	`make check`.


svn path=/trunk/; revision=292

4 files changed, 40 insertions, 22 deletions

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 1cad923..a73f832 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -12,7 +12,7 @@ AUTOMAKE_OPTIONS = 1.6
 DOC_MODULE=totem-pl-parser
 
 # The top-level SGML file. You can change this if you want to.
-DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
 
 # The directory containing the source code. Relative to $(srcdir).
 # gtk-doc will search all .c & .h files beneath here for inline comments
@@ -29,7 +29,7 @@ SCAN_OPTIONS=
 
 # Extra options to supply to gtkdoc-mkdb.
 # e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
-MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=totem_pl_parser
 
 # Extra options to supply to gtkdoc-mktmpl
 # e.g. MKTMPL_OPTIONS=--only-section-tmpl
@@ -95,3 +95,5 @@ include $(top_srcdir)/gtk-doc.make
 # Other files to distribute
 # e.g. EXTRA_DIST += version.xml.in
 EXTRA_DIST += version.xml.in
+
+TESTS = $(GTKDOC_CHECK)
diff --git a/docs/reference/totem-pl-parser-docs.sgml b/docs/reference/totem-pl-parser-docs.sgml
deleted file mode 100644
index ab060d7..0000000
--- a/docs/reference/totem-pl-parser-docs.sgml
+++ /dev/null
@@ -1,20 +0,0 @@
-<?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">
-<!ENTITY slash "/">
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>Totem Playlist 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>
diff --git a/docs/reference/totem-pl-parser-docs.xml b/docs/reference/totem-pl-parser-docs.xml
new file mode 100644
index 0000000..cd7a383
--- /dev/null
+++ b/docs/reference/totem-pl-parser-docs.xml
@@ -0,0 +1,30 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+	<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+	<!ENTITY version SYSTEM "version.xml">
+	<!ENTITY slash "/">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+	<bookinfo>
+		<title>Totem Playlist Parser Reference Manual</title>
+		<releaseinfo>
+			for totem-pl-parser &version;. The latest version of this documentation can be found online at
+			<ulink role="online-location" url="http://library.gnome.org/devel/totem-pl-parser/">http://library.gnome.org/devel/totem-pl-parser/</ulink>.
+		</releaseinfo>
+	</bookinfo>
+
+	<chapter id="api-reference">
+		<title>API Reference</title>
+		<xi:include href="xml/totem-pl-parser.xml"/>
+		<xi:include href="xml/totem-disc.xml"/>
+	</chapter>
+
+	<index id="api-index-full">
+		<title>Index of all symbols</title>
+		<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+	</index>
+	<index id="api-index-deprecated" role="deprecated">
+		<title>Index of deprecated symbols</title>
+		<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+	</index>
+</book>
diff --git a/docs/reference/totem-pl-parser-sections.txt b/docs/reference/totem-pl-parser-sections.txt
index 486257e..2391bae 100644
--- a/docs/reference/totem-pl-parser-sections.txt
+++ b/docs/reference/totem-pl-parser-sections.txt
@@ -1,5 +1,6 @@
 <SECTION>
 <FILE>totem-pl-parser</FILE>
+<TITLE>TotemPlParser</TITLE>
 TotemPlParser
 TotemPlParserClass
 TotemPlParserResult
@@ -16,6 +17,7 @@ totem_pl_parser_parse_date
 totem_pl_parser_add_ignored_scheme
 totem_pl_parser_add_ignored_mimetype
 TOTEM_PL_PARSER_FIELD_URI
+TOTEM_PL_PARSER_FIELD_URL
 TOTEM_PL_PARSER_FIELD_GENRE
 TOTEM_PL_PARSER_FIELD_TITLE
 TOTEM_PL_PARSER_FIELD_AUTHOR
@@ -39,7 +41,9 @@ TOTEM_PL_PARSER_FIELD_FILESIZE
 TOTEM_PL_PARSER_FIELD_LANGUAGE
 TOTEM_PL_PARSER_FIELD_CONTACT
 TOTEM_PL_PARSER_FIELD_IMAGE_URI
+TOTEM_PL_PARSER_FIELD_IMAGE_URL
 TOTEM_PL_PARSER_FIELD_DOWNLOAD_URI
+TOTEM_PL_PARSER_FIELD_DOWNLOAD_URL
 TOTEM_PL_PARSER_FIELD_ID
 TOTEM_PL_PARSER_FIELD_IS_PLAYLIST
 <SUBSECTION Standard>
@@ -51,6 +55,8 @@ TOTEM_PL_PARSER_CLASS
 TOTEM_IS_PL_PARSER_CLASS
 totem_pl_parser_error_quark
 TOTEM_PL_PARSER_ERROR
+TOTEM_TYPE_PL_PARSER_METADATA
+totem_pl_parser_metadata_get_type
 <SUBSECTION Private>
 TotemPlParserPrivate
 entry_parsed