[libgdata] [docs] Add a basic section to the documentation about the class structure
- From: Philip Withnall <pwithnall src gnome org>
- To: svn-commits-list gnome org
- Subject: [libgdata] [docs] Add a basic section to the documentation about the class structure
- Date: Wed, 13 May 2009 02:52:35 -0400 (EDT)
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><feed></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><entry></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]