GNOME.org
 

[libgdata] [docs] Fix various documentation errors

commit c6f00c3f92ab4d51fb740f28a6d77221b468b4be
Author: Philip Withnall <philip tecnocode co uk>
Date:   Mon Mar 22 16:47:09 2010 +0000

    [docs] Fix various documentation errors
    
    Fix various small documentation errors (generally broken links and typos)
    and add documentation for the properties in #GDataEntry.

 gdata/gd/gdata-gd-who.c                            |    4 +-
 gdata/gdata-entry.c                                |   79 +++++++++++++++++--
 gdata/gdata-service.h                              |    4 +-
 gdata/services/documents/gdata-documents-entry.c   |   14 +++-
 gdata/services/documents/gdata-documents-service.c |    2 +-
 gdata/services/youtube/gdata-youtube-service.h     |    2 +-
 6 files changed, 87 insertions(+), 18 deletions(-)
---
diff --git a/gdata/gd/gdata-gd-who.c b/gdata/gd/gdata-gd-who.c
index 7084e64..6dd4a63 100644
--- a/gdata/gd/gdata-gd-who.c
+++ b/gdata/gd/gdata-gd-who.c
@@ -113,7 +113,7 @@ gdata_gd_who_class_init (GDataGDWhoClass *klass)
 	/**
 	 * GDataGDWho:email-address:
 	 *
-	 * The e-mail address of the person represented by the #GDataWho.
+	 * The e-mail address of the person represented by the #GDataGDWho.
 	 *
 	 * For more information, see the
 	 * <ulink type="http" url="http://code.google.com/apis/gdata/docs/2.0/elements.html#gdWho";>GData specification</ulink>.
@@ -122,7 +122,7 @@ gdata_gd_who_class_init (GDataGDWhoClass *klass)
 	 **/
 	g_object_class_install_property (gobject_class, PROP_EMAIL_ADDRESS,
 				g_param_spec_string ("email-address",
-					"E-mail address", "The e-mail address of the person represented by the #GDataWho.",
+					"E-mail address", "The e-mail address of the person represented by the #GDataGDWho.",
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 }
diff --git a/gdata/gdata-entry.c b/gdata/gdata-entry.c
index 300fe30..4f0e4f1 100644
--- a/gdata/gdata-entry.c
+++ b/gdata/gdata-entry.c
@@ -103,9 +103,17 @@ gdata_entry_class_init (GDataEntryClass *klass)
 	parsable_class->get_namespaces = get_namespaces;
 	parsable_class->element_name = "entry";
 
+	/**
+	 * GDataEntry:title:
+	 *
+	 * A human-readable title for the entry.
+	 *
+	 * For more information, see the <ulink type="http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.title";>
+	 * Atom specification</ulink>.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_TITLE,
 				g_param_spec_string ("title",
-					"Title", "The title for this entry.",
+					"Title", "A human-readable title for the entry.",
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
@@ -125,32 +133,85 @@ gdata_entry_class_init (GDataEntryClass *klass)
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * GDataEntry:id:
+	 *
+	 * A permanent, universally unique identifier for the entry, in IRI form.
+	 *
+	 * For more information, see the <ulink type="http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.id";>
+	 * Atom specification</ulink>.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_ID,
 				g_param_spec_string ("id",
-					"ID", "The ID for this entry.",
+					"ID", "A permanent, universally unique identifier for the entry, in IRI form.",
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
-	/* Since: 0.2.0 */
+
+	/**
+	 * GDataEntry:etag:
+	 *
+	 * An identifier for a particular version of the entry. This changes every time the entry on the server changes, and can be used
+	 * for conditional retrieval and locking.
+	 *
+	 * For more information, see the <ulink type="http://code.google.com/apis/gdata/docs/2.0/reference.html#ResourceVersioning";>
+	 * GData specification</ulink>.
+	 *
+	 * Since: 0.2.0
+	 **/
 	g_object_class_install_property (gobject_class, PROP_ETAG,
 				g_param_spec_string ("etag",
-					"ETag", "The ETag for this entry.",
+					"ETag", "An identifier for a particular version of the entry.",
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataEntry:updated:
+	 *
+	 * The date and time the entry was most recently updated in a significant way.
+	 *
+	 * For more information, see the <ulink type="http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.updated";>
+	 * Atom specification</ulink>.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_UPDATED,
 				g_param_spec_boxed ("updated",
-					"Updated", "The last update time for this entry.",
+					"Updated", "The date and time the entry was most recently updated in a significant way.",
 					GDATA_TYPE_G_TIME_VAL,
 					G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataEntry:published:
+	 *
+	 * The date and time the entry was first published or made available.
+	 *
+	 * For more information, see the <ulink type="http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.published";>
+	 * Atom specification</ulink>.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_PUBLISHED,
 				g_param_spec_boxed ("published",
-					"Published", "The time this entry was published.",
+					"Published", "The date and time the entry was first published or made available.",
 					GDATA_TYPE_G_TIME_VAL,
 					G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataEntry:content:
+	 *
+	 * The content of the entry.
+	 *
+	 * For more information, see the <ulink type="http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.published";>
+	 * Atom specification</ulink>.
+	 **/
 	g_object_class_install_property (gobject_class, PROP_CONTENT,
 				g_param_spec_string ("content",
-					"Content", "The textual content of this entry.",
+					"Content", "The content of the entry.",
 					NULL,
 					G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+	/**
+	 * GDataEntry:is-inserted:
+	 *
+	 * Whether the entry has been inserted on the server. This is %FALSE for entries which have just been created using gdata_entry_new() and
+	 * %TRUE for entries returned from the server by queries. It is set to %TRUE when an entry is inserted using gdata_service_insert().
+	 **/
 	g_object_class_install_property (gobject_class, PROP_IS_INSERTED,
 				g_param_spec_boolean ("is-inserted",
 					"Inserted?", "Whether the entry has been inserted on the server.",
@@ -159,7 +220,7 @@ gdata_entry_class_init (GDataEntryClass *klass)
 	/**
 	 * GDataEntry:rights:
 	 *
-	 * The ownership rights pertaining to this entry. 
+	 * The ownership rights pertaining to the entry.
 	 *
 	 * For more information, see the <ulink type="http://www.atomenabled.org/developers/syndication/atom-format-spec.php#element.rights";>
 	 * Atom specification</ulink>.
@@ -168,7 +229,7 @@ gdata_entry_class_init (GDataEntryClass *klass)
 	 **/
 	g_object_class_install_property (gobject_class, PROP_RIGHTS,
 					 g_param_spec_string ("rights",
-							      "Rights", "Rights pertaining to the entry.",
+							      "Rights", "The ownership rights pertaining to the entry.",
 							      NULL,
 							      G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 }
diff --git a/gdata/gdata-service.h b/gdata/gdata-service.h
index 66e8784..5f9cc41 100644
--- a/gdata/gdata-service.h
+++ b/gdata/gdata-service.h
@@ -82,13 +82,13 @@ typedef enum {
  * directly to resolve the issue before logging in using a non-Google application.
  * @GDATA_AUTHENTICATION_ERROR_TERMS_NOT_AGREED: The user has not agreed to terms. The user will need to access their Google account directly to
  * resolve the issue before logging in using a non-Google application.
- * @GDATA_AUTHENTICATION_ERROR_CAPTCHA_REQUIRED: A CAPTCHA is required. (A response with this error code will also contain an image URL and a
+ * @GDATA_AUTHENTICATION_ERROR_CAPTCHA_REQUIRED: A CAPTCHA is required. (A response with this error code will also contain an image URI and a
  * CAPTCHA token.)
  * @GDATA_AUTHENTICATION_ERROR_ACCOUNT_DELETED: The user account has been deleted.
  * @GDATA_AUTHENTICATION_ERROR_ACCOUNT_DISABLED: The user account has been disabled.
  * @GDATA_AUTHENTICATION_ERROR_SERVICE_DISABLED: The user's access to the specified service has been disabled. (The user account may still be valid.)
  *
- * Error codes for #GDataDataService authentication operations. See http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html#Errors for
+ * Error codes for #GDataService authentication operations. See http://code.google.com/apis/accounts/docs/AuthForInstalledApps.html#Errors for
  * the official reference.
  **/
 typedef enum {
diff --git a/gdata/services/documents/gdata-documents-entry.c b/gdata/services/documents/gdata-documents-entry.c
index a189dff..ab33fe5 100644
--- a/gdata/services/documents/gdata-documents-entry.c
+++ b/gdata/services/documents/gdata-documents-entry.c
@@ -413,11 +413,15 @@ gdata_documents_entry_get_last_viewed (GDataDocumentsEntry *self, GTimeVal *last
  * gdata_documents_entry_get_path:
  * @self: a #GDataDocumentsEntry
  *
- * Gets the #GDataDocumentsEntry:path property.
+ * Builds a path for the #GDataDocumentsEntry, starting from a root node and traversing the folders containing the document, then
+ * ending with the document's ID.
  *
- * Note: the path is based on the entry ID, and not the entry human readable name (#GDataEntry::title).
+ * An example path would be: "/folder_id1/folder_id2/document_id".
  *
- * Return value: the folder hierarchy path containing the entry, or %NULL; free with g_free()
+ * Note: the path is based on the entry/document IDs of the folders (#GDataEntry:id) and document (#GDataDocumentsEntry:document-id),
+ * and not the entries' human-readable names (#GDataEntry:title).
+ *
+ * Return value: the folder hierarchy path containing the document, or %NULL; free with g_free()
  *
  * Since: 0.4.0
  **/
@@ -438,6 +442,9 @@ gdata_documents_entry_get_path (GDataDocumentsEntry *self)
 		gchar *folder_id = NULL;
 		gchar **link_href_cut = g_strsplit (gdata_link_get_uri (GDATA_LINK (element->data)), "/", 0);
 
+		/* Extract the folder ID from the folder URI, which is of the form:
+		 *   http://docs.google.com/feeds/documents/private/full/folder%3Afolder_id
+		 * We want the "folder_id" bit. */
 		for (i = 0;; i++) {
 			gchar **path_cut = NULL;
 
@@ -457,6 +464,7 @@ gdata_documents_entry_get_path (GDataDocumentsEntry *self)
 		g_strfreev (link_href_cut);
 		g_assert (folder_id != NULL);
 
+		/* Append the folder ID to our path */
 		g_string_append (path, folder_id);
 		g_string_append_c (path, '/');
 		g_free (folder_id);
diff --git a/gdata/services/documents/gdata-documents-service.c b/gdata/services/documents/gdata-documents-service.c
index db05681..657a21e 100644
--- a/gdata/services/documents/gdata-documents-service.c
+++ b/gdata/services/documents/gdata-documents-service.c
@@ -218,7 +218,7 @@ gdata_documents_service_query_documents (GDataDocumentsService *self, GDataDocum
  * @document_type should be the expected type of the document to be returned. e.g. %GDATA_TYPE_DOCUMENTS_SPREADSHEET if you're querying
  * for a spreadsheet.
  *
- * @document_id should be the ID of the document as returned by gdata_document_entry_get_document_id().
+ * @document_id should be the ID of the document as returned by gdata_documents_entry_get_document_id().
  *
  * Parameters and errors are as for gdata_service_query().
  *
diff --git a/gdata/services/youtube/gdata-youtube-service.h b/gdata/services/youtube/gdata-youtube-service.h
index 4a95f6f..28bf9ca 100644
--- a/gdata/services/youtube/gdata-youtube-service.h
+++ b/gdata/services/youtube/gdata-youtube-service.h
@@ -43,7 +43,7 @@ G_BEGIN_DECLS
  * @GDATA_YOUTUBE_RECENTLY_FEATURED_FEED: This feed contains videos recently featured on the YouTube home page or featured videos tab.
  * @GDATA_YOUTUBE_WATCH_ON_MOBILE_FEED: This feed contains videos suitable for playback on mobile devices.
  *
- * Standard feed types for standard feed queries with gata_youtube_service_query_standard_feed(). For more information, see
+ * Standard feed types for standard feed queries with gdata_youtube_service_query_standard_feed(). For more information, see
  * the <ulink type="http" url="http://code.google.com/apis/youtube/2.0/developers_guide_protocol.html#Standard_feeds";>online documentation</ulink>.
  **/
 typedef enum {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]