[gnome-panel] [clock] Document the meaning of the return values for CanSetTime(zone)

[Vincent Untz <vuntz src gnome org>]

commit d43b65e8ad3fcc2730de691197d88926d2ec98cb
Author: Vincent Untz <vuntz gnome org>
Date:   Tue Aug 11 20:30:41 2009 +0200

    [clock] Document the meaning of the return values for CanSetTime(zone)

 applets/clock/clock.c                          |    2 +
 applets/clock/gnome-clock-applet-mechanism.xml |   50 +++++++++++++++++++++++-
 2 files changed, 50 insertions(+), 2 deletions(-)
---
diff --git a/applets/clock/clock.c b/applets/clock/clock.c
index 7ce582c..e264a54 100644
--- a/applets/clock/clock.c
+++ b/applets/clock/clock.c
@@ -1628,6 +1628,8 @@ update_set_time_button (ClockData *cd)
 {
 	gint can_set;
 
+	/* this returns more than just a boolean; check the documentation of
+	 * the dbus method for more information */
 	can_set = can_set_system_time ();
 
 	if (cd->time_settings_button)
diff --git a/applets/clock/gnome-clock-applet-mechanism.xml b/applets/clock/gnome-clock-applet-mechanism.xml
index 9845fa8..eabc531 100644
--- a/applets/clock/gnome-clock-applet-mechanism.xml
+++ b/applets/clock/gnome-clock-applet-mechanism.xml
@@ -7,7 +7,30 @@
     </method>
     <method name="CanSetTimezone">
       <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
-      <arg name="value" direction="out" type="i"/>
+      <arg name="value" direction="out" type="i">
+        <doc:doc>
+          <doc:summary>Whether the caller can set the timezone</doc:summary>
+          <doc:description>
+            <doc:para>
+              The return value is not a boolean, but an integer with the following meaning:
+              <doc:list>
+                <doc:item>
+                  <doc:term>0</doc:term>
+                  <doc:definition>the caller cannot set the timezone</doc:definition>
+                </doc:item>
+                <doc:item>
+                  <doc:term>1</doc:term>
+                  <doc:definition>the caller will be challenged before being able to set the timezone</doc:definition>
+                </doc:item>
+                <doc:item>
+                  <doc:term>2</doc:term>
+                  <doc:definition>the caller is authorized to set the timezone</doc:definition>
+                </doc:item>
+              </doc:list>
+            </doc:para>
+          </doc:description>
+        </doc:doc>
+      </arg>
     </method>
     <method name="SetTime">
       <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
@@ -15,7 +38,30 @@
     </method>
     <method name="CanSetTime">
       <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>
-      <arg name="value" direction="out" type="i"/>
+      <arg name="value" direction="out" type="i">
+        <doc:doc>
+          <doc:summary>Whether the caller can set the time</doc:summary>
+          <doc:description>
+            <doc:para>
+              The return value is not a boolean, but an integer with the following meaning:
+              <doc:list>
+                <doc:item>
+                  <doc:term>0</doc:term>
+                  <doc:definition>the caller cannot set the time</doc:definition>
+                </doc:item>
+                <doc:item>
+                  <doc:term>1</doc:term>
+                  <doc:definition>the caller will be challenged before being able to set the time</doc:definition>
+                </doc:item>
+                <doc:item>
+                  <doc:term>2</doc:term>
+                  <doc:definition>the caller is authorized to set the time</doc:definition>
+                </doc:item>
+              </doc:list>
+            </doc:para>
+          </doc:description>
+        </doc:doc>
+      </arg>
     </method>
     <method name="AdjustTime">
       <annotation name="org.freedesktop.DBus.GLib.Async" value=""/>