[libgdata] [docs] Add a philosophy section to the documentation

From: Philip Withnall <pwithnall src gnome org>
To: commits-list gnome org
Cc:
Subject: [libgdata] [docs] Add a philosophy section to the documentation
Date: Fri, 26 Mar 2010 19:36:38 +0000 (UTC)
commit 37376eb3e63da22c4ba766988810d4a0b72f8e84
Author: Philip Withnall <philip tecnocode co uk>
Date:   Fri Mar 26 19:35:25 2010 +0000

    [docs] Add a philosophy section to the documentation
    
    This section gives some details about some of the design decisions in
    libgdata which have affected the API.
    
    This also updates the HACKING file, with references to the new documentation
    sections, and a few updated commenting rules.

 HACKING                           |   21 +++++++++++++++-
 docs/reference/gdata-overview.xml |   47 ++++++++++++++++++++++++++++++++++--
 2 files changed, 63 insertions(+), 5 deletions(-)
---
diff --git a/HACKING b/HACKING
index 45ea847..846febc 100644
--- a/HACKING
+++ b/HACKING
@@ -55,10 +55,14 @@ libgdata employs:
 
 	* Return value: a new #GDataEntry; unref with g_object_unref()
 
-   If the function can also return NULL (on error), format it as follows:
+   If the function can also return NULL (on error, for example) or some other "default" value (-1, 0, etc.), format it as follows:
 
 	* Return value: a new #GDataGDFeedLink, or %NULL; free with gdata_gd_feed_link_free()
 
+   Note that if a function returns NULL as a result of a precondition or assertion failure, this should not be listed in the documentation. The
+   precondition itself may be listed in the function documentation prose, but if it's the only reason for a function to return NULL, the "or %NULL"
+   clause should be omitted.
+
  - When adding API, make sure to add a "Since" clause:
 
 	* Since: 0.2.0
@@ -71,7 +75,12 @@ libgdata employs:
 
 	* @updated_max: the new maximum update time, or %NULL
 
- - If numbers are mentioned in documentation as values to be passed around in code, they should be prefixed by a '%', just like %NULL.
+ - If numbers, such as %-1, are mentioned in documentation as values to be passed around in code, they should be prefixed by a '%', just like %NULL.
+
+ - The documentation explaining the purpose of a property, its limitations, interpretation, etc., should be given in the gtk-doc comment for the
+   GObject property itself, not in the documentation for its getter or setter. The documentation for the getter and setter should be stubs which
+   refer to the property's documentation. The getter and setter documentation should, however, still include full details about whether NULL values
+   are permissible for the function parameters, or are possible as the return value, for example.
 
 Adding public API
 =================
@@ -98,6 +107,12 @@ Adding public API
  - All GObject *_get_type function declarations must be tagged with the G_GNUC_CONST macro, as well as any other applicable functions
    (see the gcc documentation: http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bconst_007d-function-attribute-2207).
 
+ - All properties which could be considered to use an enumerated value should almost definitely use a string instead. See the documentation section
+   on "Enumerable Properties" in the "GData Overview" section.
+
+ - New services should be implemented in libgdata itself, not by applications which use libgdata. See the documentation section on "New Services" in
+   the "GData Overview" section.
+
 Choosing function names
 =======================
 
@@ -125,6 +140,8 @@ The short explanation of a commit should always be prefixed by a tag to describe
 
  - [atom] â?? for the Atom-namespaced code in the gdata/atom directory.
 
+ - [gcontact] â?? for the gContact-namespaced code in the gdata/gcontact directory.
+
  - [gd] â?? for the GData-namespaced code in the gdata/gd directory.
 
  - [media] â?? for the Media RSS-namespaced code in the gdata/media directory.
diff --git a/docs/reference/gdata-overview.xml b/docs/reference/gdata-overview.xml
index 9b9ad8f..425b32b 100644
--- a/docs/reference/gdata-overview.xml
+++ b/docs/reference/gdata-overview.xml
@@ -53,8 +53,8 @@
 						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
+						<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>
@@ -63,7 +63,8 @@
 						<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>
+						<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>
@@ -92,4 +93,44 @@
 			</variablelist>
 		</refsect2>
 	</refsect1>
+
+	<refsect1>
+		<title>Development Philosophy</title>
+		<para>As the GData protocol (and all the service-specific protocols which extend it) is reasonably young, it is subject to fairly
+			frequent updates and expansions. While backwards compatibility is maintained, these updates necessitate that libgdata
+			remains fairly flexible in how it treats data. The sections below detail some of the ways in which libgdata achieves this,
+			and the reasoning behind them.</para>
+
+		<refsect2>
+			<title>Enumerable Properties</title>
+			<para>There are many class properties in libgdata which should, at first glance, be implemented as enumerated types. Function
+				calls such as <function><link linkend="gdata-link-get-relation-type">gdata_link_get_relation_type()</link></function>
+				and <function><link linkend="gdata-gd-im-address-get-protocol">gdata_gd_im_address_get_protocol()</link></function>
+				would, in a conventional library, return a value from an enum, which would work well, and be more typesafe and
+				memory-efficient than using arbitrary strings.</para>
+			<para>However, such an implementation would not be forwards-compatible. If a protocol addition was made which added another
+				link relation type, or added supportf or another IM protocol, there would be no way for libgdata to represent some
+				of the data it retrieved from the server. It could return an "other" value from the enum, but that could lead to
+				data loss in the common case of GData entries being queried from the server, processed, then updated again.</para>
+			<para>For this reason â?? which is made more troublesome by the fact that it is unpredictable when updates to the protocol are
+				released, or when updated XML will start coming over the wire â?? libgdata uses enumerated types sparingly; they are
+				only used when it is very improbable (or even impossible) for the property in question to be extended or changed in
+				the future. In any other case, a string value is used instead, with libgdata providing <code>#define</code>d values
+				for the known values of the property. These values should be used as much as possible by applications which use
+				libgdata (i.e. they should be treated as if they were enumerated values), but applications are free to use strings
+				of their own, too. All validation of such pseudi-enums is left to the server.</para>
+		</refsect2>
+
+		<refsect2>
+			<title>New Services</title>
+			<para>The API required to implement support for a new service using libgdata is not publicly exposed. This is because doing
+				so would clutter the API to a large extent; for example, exposing various properties as writeable which are currently
+				only readable. While the freedom for users of libgdata to write their own services is a good one, it is outweighed by
+				the muddlement that this would bring to the API.</para>
+			<para>Furthermore, since it is highly unlikely that anyone except Google will use GData as a basis for communicating with
+				their service, there is little harm in restricting the implementation of services to libgdata. If someone wants to
+				implement support for a new GData service, it is for the benefit of everyone if this implementation is done in libgdata
+				itself, rather than their application.</para>
+		</refsect2>
+	</refsect1>
 </refentry>
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]