[libgdata/libgdata-0-6] [docs] Fix various documentation errors
- From: Philip Withnall <pwithnall src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libgdata/libgdata-0-6] [docs] Fix various documentation errors
- Date: Mon, 29 Mar 2010 21:31:02 +0000 (UTC)
commit 3558a8975c099c8a892c5bbf08399ff523cea0a6
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]