Merge lp:~rainct/libzeitgeist/776651-doc into lp:libzeitgeist

[Siegfried Gevatter]

[Mikkel Kamstrup Erlandsen (kamstrup)]

30 +/**
31 + * zeitgeist_subject_get_current_uri:
32 + * @subject: The subject to get the current_uri from
33 + *
34 + * Get the current_uri of a subject.
35 + * This attribute is only significant for subjects for a
36 + * #ZEITGEIST_ZG_MOVE_EVENT.
37 + *
38 + * Returns: The current_uri of @subject.
39 + *
40 + * Since: 0.3.14
41 + */

This is not entirely true is guess?

If a file has been deleted and zg registers it then the current_uri will be NULL, no? And current_uri != uri if at any point in the past Zg has seen a MOVE_EVENT on uri - the ocs make it sounds like it is only relevant when the subject instance is embedded in a MoveEvent instance..?

review: Needs Fixing

[Siegfried Gevatter (rainct)]

Good catch. Didn't remember how weird our move events are :P.

How about this?

/**
 * zeitgeist_subject_get_current_uri:
 * @subject: The subject to get the current_uri from
 *
 * Get the current_uri of a subject.
 *
 * This is the updated URI taking into account possible relocations of the resource.
 * It is illegal to insert an event with subjects having a `current_uri' different
 * than their `uri'.
 *
 * A special case is events with #ZEITGEIST_ZG_MOVE_EVENT interpretation. In this
 * case, `current_uri' is the destination to which `uri' is being moved, and they
 * are expected to be different.
 *
 * Returns: The current_uri of @subject.
 *
 * Since: 0.3.14
 */

[Mikkel Kamstrup Erlandsen (kamstrup)]

Yep. Sounds spot on to me.

=== modified file 'src/zeitgeist-event.c'
--- src/zeitgeist-event.c	2012-02-02 09:56:38 +0000
+++ src/zeitgeist-event.c	2012-02-02 14:57:19 +0000
@@ -441,6 +441,8 @@
  * from, not where it resides.
  *
  * Returns: The origin of @event.
+ *
+ * Since: 0.3.14
  */
 const gchar*
 zeitgeist_event_get_origin (ZeitgeistEvent *event)
@@ -460,6 +462,8 @@
  * Set the origin of an event.
  * This differs from a subject's origin, as it describes where the event comes
  * from, not where it resides.
+ *
+ * Since: 0.3.14
  */
 void
 zeitgeist_event_set_origin (ZeitgeistEvent *event,

=== modified file 'src/zeitgeist-subject.c'
--- src/zeitgeist-subject.c	2012-01-31 14:25:11 +0000
+++ src/zeitgeist-subject.c	2012-02-02 14:57:19 +0000
@@ -248,6 +248,18 @@
   priv->storage = copy;
 }
 
+/**
+ * zeitgeist_subject_get_current_uri:
+ * @subject: The subject to get the current_uri from
+ *
+ * Get the current_uri of a subject.
+ * This attribute is only significant for subjects for a
+ * #ZEITGEIST_ZG_MOVE_EVENT.
+ *
+ * Returns: The current_uri of @subject.
+ *
+ * Since: 0.3.14
+ */
 const gchar*
 zeitgeist_subject_get_current_uri (ZeitgeistSubject *subject)
 {
@@ -257,6 +269,18 @@
   return priv->current_uri;
 }
 
+/**
+ * zeitgeist_subject_set_current_uri:
+ * @subject: The subject to set the current_uri for
+ * @current_uri: The current_uri to set
+ *
+ * Set the current_uri of a subject.
+ * It is illegal to give this attribute a value other than the subject's
+ * URI (as returned by zeitgeist_subject_get_uri()), unless used with a
+ * #ZEITGEIST_ZG_MOVE_EVENT.
+ *
+ * Since: 0.3.14
+ */
 void
 zeitgeist_subject_set_current_uri (ZeitgeistSubject *subject,
                                    const gchar *current_uri)