[libgdata] [docs] Add a basic section to the documentation about the class structure



commit 710d8a8281c341d124e74c8d039253cf8124736c
Author: Philip Withnall <philip tecnocode co uk>
Date:   Tue May 12 22:14:41 2009 +0100

    [docs] Add a basic section to the documentation about the class structure
---
 docs/reference/Makefile.am                     |    6 +-
 docs/reference/gdata-docs.xml                  |   22 ++++++-
 docs/reference/gdata-overview.xml              |   74 ++++++++++++++++++++++++
 docs/reference/structure.dia                   |  Bin 0 -> 1814 bytes
 docs/reference/structure.png                   |  Bin 0 -> 17149 bytes
 gdata/services/calendar/gdata-calendar-event.c |    2 +-
 6 files changed, 97 insertions(+), 7 deletions(-)

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 6453ede..6b3386b 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -51,11 +51,11 @@ IGNORE_HFILES=common.h gdata-private.h gdata-marshal.h gdata-enums.h
 
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
-HTML_IMAGES=
+HTML_IMAGES=structure.png
 
 # 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=version.xml
+content_files=version.xml gdata-overview.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
@@ -92,7 +92,7 @@ GITIGNOREFILES = tmpl/
 
 # Other files to distribute
 # e.g. EXTRA_DIST += version.xml.in
-EXTRA_DIST += version.xml.in
+EXTRA_DIST += version.xml.in structure.dia
 
 if ENABLE_GTK_DOC
 TESTS_ENVIRONMENT = cd $(srcdir) && 
diff --git a/docs/reference/gdata-docs.xml b/docs/reference/gdata-docs.xml
index 1152c9b..e024e69 100644
--- a/docs/reference/gdata-docs.xml
+++ b/docs/reference/gdata-docs.xml
@@ -12,6 +12,11 @@
 	</bookinfo>
 
 	<chapter>
+		<title>GData Overview</title>
+		<xi:include href="gdata-overview.xml"/>
+	</chapter>
+
+	<chapter>
 		<title>Core API</title>
 		<xi:include href="xml/gdata-service.xml"/>
 		<xi:include href="xml/gdata-query.xml"/>
@@ -24,6 +29,7 @@
 		<title>Namespace API</title>
 		<xi:include href="xml/gdata-atom.xml"/>
 		<xi:include href="xml/gdata-gdata.xml"/>
+		<xi:include href="xml/gdata-media.xml"/>
 		<xi:include href="xml/gdata-youtube.xml"/>
 	</chapter>
 
@@ -55,8 +61,18 @@
 
 	<index id="api-index-full">
 		<title>API Index</title>
-		<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+		<xi:include href="xml/api-index-full.xml"><xi:fallback/></xi:include>
+	</index>
+	<index role="0.1.1">
+		<title>Index of new symbols in 0.1.1</title>
+		<xi:include href="xml/api-index-0.1.1.xml"><xi:fallback/></xi:include>
+	</index>
+	<index role="0.2.0">
+		<title>Index of new symbols in 0.2.0</title>
+		<xi:include href="xml/api-index-0.2.0.xml"><xi:fallback/></xi:include>
+	</index>
+	<index role="0.3.0">
+		<title>Index of new symbols in 0.3.0</title>
+		<xi:include href="xml/api-index-0.3.0.xml"><xi:fallback/></xi:include>
 	</index>
-
-	<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
 </book>
diff --git a/docs/reference/gdata-overview.xml b/docs/reference/gdata-overview.xml
new file mode 100644
index 0000000..d431c56
--- /dev/null
+++ b/docs/reference/gdata-overview.xml
@@ -0,0 +1,74 @@
+<refentry id="gdata-overview">
+	<refmeta>
+		<refentrytitle role="top_of_page" id="gdata-overview.top_of_page">GData Overview</refentrytitle>
+		<manvolnum>3</manvolnum>
+		<refmiscinfo>GDATA Library</refmiscinfo>
+	</refmeta>
+	<refnamediv>
+		<refname>GData Overview</refname>
+		<refpurpose>overview of libgdata's architecture</refpurpose>
+	</refnamediv>
+
+	<refsect1>
+		<title>Introduction</title>
+		<para>libgdata is a library to allow access to web services using the GData protocol from the desktop. The <ulink type="http"
+			url="http://code.google.com/apis/gdata/overview.html";>GData protocol</ulink> is a simple protocol for reading and writing
+			data on the web, designed by Google.</para>
+
+		<refsect2>
+			<title>Structure</title>
+			<para>The basic design of libgdata mirrors the protocol's structure quite closely:
+				<figure>
+					<mediaobject>
+						<imageobject><imagedata fileref="structure.png" format="PNG" align="center"/></imageobject>
+					</mediaobject>
+					<textobject><phrase>An overview of the libgdata class structure.</phrase></textobject>
+				</figure>
+			</para>
+			<variablelist>
+				<varlistentry>
+					<term><type><link linkend="GDataService">GDataService</link></type></term>
+					<listitem><para>Subclassed for each different web service implemented, this class represents a single client's
+						connection to the relevant web service, holding their authentication state, and making the necessary
+						requests to read and write data to and from the service. All top-level actions, such as creating a new
+						object on the server, are carried out through a service.</para>
+						<para>There should be one <type><link linkend="GDataService">GDataService</link></type> subclass for each
+						of the services listed <ulink type="http" url="http://code.google.com/apis/gdata/";>in the GData
+						documentation</ulink>.</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><type><link linkend="GDataQuery">GDataQuery</link></type></term>
+					<listitem><para>For queries to have multiple individual parameters, a
+						<type><link linkend="GDataQuery">GDataQuery</link></type> can be used to specify the parameters.</para>
+						<para>Query objects are optional, and can only be used with queries (not with entry insertions, updates
+						or deletions). The query object builds the query URI used by the
+						<type><link linkend="GDataService">GDataService</link></type> when sending the query to the server.</para>
+						<para>Services can subclass <type><link linkend="GDataQuery">GDataQuery</link></type> if the service
+						supports non-standard query parameters.</para>
+					</listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><type><link linkend="GDataFeed">GDataFeed</link></type></term>
+					<listitem><para>Effectively a list of <type><link linkend="GDataEntry">GDataEntry</link></type>s, the
+						<type><link linkend="GDataFeed">GDataFeed</link></type> class is a direct counterpart of the root
+						<type>&lt;feed&gt;</type> element in the Atom feeds which form the GData protocol. It contains the
+						elements in a query response, as well as general information about the response, such as links to
+						related feeds and the categories under which the query response falls.</para>
+						<para><type><link linkend="GDataFeed">GDataFeed</link></type> is usually not subclassed by services,
+						as there are rarely service-specific elements in a feed itself.</para></listitem>
+				</varlistentry>
+				<varlistentry>
+					<term><type><link linkend="GDataEntry">GDataEntry</link></type></term>
+					<listitem><para>A <type><link linkend="GDataEntry">GDataEntry</link></type> is a direct counterpart of the
+						<type>&lt;entry&gt;</type> element in the Atom feeds which form the GData protocol. It represents a
+						single object of unspecified semantics; an entry could be anything from a calendar event to a video
+						comment or access control rule. Semantics are given to entries by subclassing
+						<type><link linkend="GDataEntry">GDataEntry</link></type> for the various types of entries returned
+						by queries to a service. Such subclasses implement useful, relevant and query-specific properties
+						on the entry (such as the duration of a video, or the recurrence rules of a calendar event).</para>
+					</listitem>
+				</varlistentry>
+			</variablelist>
+		</refsect2>
+	</refsect1>
+</refentry>
diff --git a/docs/reference/structure.dia b/docs/reference/structure.dia
new file mode 100644
index 0000000..3b39c69
Binary files /dev/null and b/docs/reference/structure.dia differ
diff --git a/docs/reference/structure.png b/docs/reference/structure.png
new file mode 100644
index 0000000..25f3b5d
Binary files /dev/null and b/docs/reference/structure.png differ
diff --git a/gdata/services/calendar/gdata-calendar-event.c b/gdata/services/calendar/gdata-calendar-event.c
index 6b4ae5a..653ed74 100644
--- a/gdata/services/calendar/gdata-calendar-event.c
+++ b/gdata/services/calendar/gdata-calendar-event.c
@@ -1311,7 +1311,7 @@ gdata_calendar_event_get_original_event_details (GDataCalendarEvent *self, gchar
  *
  * Return value: %TRUE if the event is an exception, %FALSE otherwise
  *
- * Since: 0.3.0.
+ * Since: 0.3.0
  **/
 gboolean
 gdata_calendar_event_is_exception (GDataCalendarEvent *self)



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]