[Telepathy-commits] [telepathy-spec/master] Account*: Add missing cross-references

Will Thompson will.thompson at collabora.co.uk
Thu Nov 20 10:35:45 PST 2008


---
 spec/Account.xml                  |   57 ++++++++++++++++++++++++------------
 spec/Account_Interface_Avatar.xml |    2 +
 spec/Account_Manager.xml          |    5 ++-
 3 files changed, 43 insertions(+), 21 deletions(-)

diff --git a/spec/Account.xml b/spec/Account.xml
index e5b755f..ea0c646 100644
--- a/spec/Account.xml
+++ b/spec/Account.xml
@@ -33,8 +33,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           that appears in the connection manager's well-known bus name and
           object path</li>
         <li><em>proto</em> is the <tp:type>Protocol</tp:type> name as seen in
-          ConnectionManager.ListProtocols, but with "-" replaced with "_"
-          (i.e. the same as in the object-path of a Connection)</li>
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy">ConnectionManager.ListProtocols</tp:dbus-ref>,
+          but with "-" replaced with "_"
+          (i.e. the same as in the object-path of a <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>)</li>
         <li><em>acct</em> is an arbitrary string of ASCII letters, digits
           and underscores, starting with a letter or underscore, which
           uniquely identifies this account</li>
@@ -123,9 +126,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         This account has been removed.
 
         <tp:rationale>
-          This is redundant with AccountRemoved, but it's still worth having,
+          This is redundant with <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.AccountManager">AccountRemoved</tp:dbus-ref>,
+          but it's still worth having,
           to avoid having to bind to AccountManager.AccountRemoved to tell
-          you whether your Account is valid - ideally, an account-editing UI
+          you whether your Account is valid — ideally, an account-editing UI
           should only care about a single Account.
         </tp:rationale>
       </tp:docstring>
@@ -142,7 +147,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
       <arg name="Properties" type="a{sv}">
         <tp:docstring>
-          A map from property names in this namespace (e.g. Nickname) to
+          A map from property names in this namespace (e.g.
+          <tp:member-ref>Nickname</tp:member-ref>) to
           values. Properties whose values have not changed SHOULD be
           omitted, but this need not be done.
         </tp:docstring>
@@ -240,7 +246,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <tp:docstring>
         The nickname to set on this account for display to other contacts,
         as set by the user. When the account becomes connected, the
-        account manager SHOULD set this as the user's alias using SetAliases
+        account manager SHOULD set this as the user's alias using <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Connection.Interface.Aliasing">SetAliases</tp:dbus-ref>
         if appropriate.
 
         <tp:rationale>
@@ -258,12 +265,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       type="a{sv}" access="read">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>A map from connection manager parameter names (as in the
-          ConnectionManager interface) to their values. This property includes
+          <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy">ConnectionManager</tp:dbus-ref>
+          interface) to their values. This property includes
           only those parameters that are stored for this account, and SHOULD
           only include those parameters that the user has explicitly set.
         </p>
         <p>This property cannot be altered using Set() - use
-          UpdateParameters instead.</p>
+          <tp:member-ref>UpdateParameters</tp:member-ref> instead.</p>
 
         <tp:rationale>
           This avoids NMC being tied to gconf as a matter of API.
@@ -273,7 +282,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
     <method name="UpdateParameters" tp:name-for-bindings="Update_Parameters">
       <tp:docstring>
-        Change the value of the Parameters property. Any changes will not
+        Change the value of the <tp:member-ref>Parameters</tp:member-ref> property. Any changes will not
         take effect until the next time the account is disconnected and
         reconnected.
 
@@ -330,11 +339,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       tp:name-for-bindings="Connect_Automatically">
       <tp:docstring>
         If true, the account manager SHOULD attempt to put this account
-        online with the AutomaticPresence whenever possible (in the base
+        online with the <tp:member-ref>AutomaticPresence</tp:member-ref>
+        whenever possible (in the base
         Account interface this is deliberately left vague). If false,
         it MUST NOT put the account online automatically in response to,
         for instance, connectivity changes, but SHOULD still put the account
-        online with the AutomaticPresence if requested by the user (for
+        online with the <tp:member-ref>AutomaticPresence</tp:member-ref> if
+        requested by the user (for
         instance, if the user tries to start a conversation using this
         account).
 
@@ -360,7 +371,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
     <property name="ConnectionStatus" type="u" access="read"
       tp:name-for-bindings="Connection_Status">
       <tp:docstring>
-        If the Connection property is non-empty, the status of that connection.
+        If the <tp:member-ref>Connection</tp:member-ref> property is non-empty,
+        the status of that connection.
         If the Connection property is the empty string, this property may
         either be Disconnected (indicating that the account manager is not
         attempting to bring it online), or Connecting (indicating that the
@@ -380,7 +392,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
     <property name="ConnectionStatusReason" type="u" access="read"
       tp:name-for-bindings="Connection_Status_Reason">
       <tp:docstring>
-        The reason for the last change to ConnectionStatus.
+        The reason for the last change to
+        <tp:member-ref>ConnectionStatus</tp:member-ref>.
         The account manager is expected to set this by observing signals
         from the Connection.
 
@@ -397,7 +410,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <tp:docstring>
         The actual presence. If the connection is not online, this should be
         (Connection_Presence_Type_Offline, "", "").
-        If the connection is online but does not support the Presence
+        If the connection is online but does not support the <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref>
         interface, this should be (Connection_Presence_Type_Unset, "", "").
         The account manager is expected to set this by observing signals
         from the Connection.
@@ -412,14 +426,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       tp:type="Simple_Presence" tp:name-for-bindings="Requested_Presence">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The requested presence for this account. When this is changed, the
-          account manager should attempt to manipulate the connection manager
-          to make CurrentPresence match RequestedPresence as closely as
+        account manager should attempt to manipulate the connection manager to
+        make <tp:member-ref>CurrentPresence</tp:member-ref> match
+        <tp:member-ref>RequestedPresence</tp:member-ref> as closely as
           possible. It should not be saved to any sort of persistent
           storage.</p>
 
         <p>When the account manager automatically connects an account,
           it must signal this by setting the RequestedPresence to the same
-          thing as the AutomaticPresence.</p>
+          thing as the <tp:member-ref>AutomaticPresence</tp:member-ref>.</p>
 
         <tp:rationale>
           This corresponds to e.g. GetPresence and GetPresenceMessage
@@ -432,8 +447,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       tp:name-for-bindings="Normalized_Name">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>The normalized user ID of the local user on this account (i.e. the
-          string returned when the InspectHandle method is called on the
-          result of GetSelfHandle() for an active connection).</p>
+          string returned when the <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
+          method is called on the
+          result of <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Connection">GetSelfHandle</tp:dbus-ref>
+          for an active connection).</p>
         
         <p>It is unspecified whether this user ID is globally unique.</p>
 
diff --git a/spec/Account_Interface_Avatar.xml b/spec/Account_Interface_Avatar.xml
index 3d0c2a9..6c85b8e 100644
--- a/spec/Account_Interface_Avatar.xml
+++ b/spec/Account_Interface_Avatar.xml
@@ -20,6 +20,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 </p>
   </tp:license>
   <interface name="org.freedesktop.Telepathy.Account.Interface.Avatar">
+    <tp:requires interface="org.freedesktop.Telepathy.Account"/>
+
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>This interface extends the core Account interface to provide a
         user-settable avatar image.</p>
diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml
index b92913e..c534e34 100644
--- a/spec/Account_Manager.xml
+++ b/spec/Account_Manager.xml
@@ -63,7 +63,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       tp:name-for-bindings="Valid_Accounts">
       <tp:docstring>
         A list of the valid (complete, usable) accounts. Change notification
-        is via AccountValidityChanged.
+        is via <tp:member-ref>AccountValidityChanged</tp:member-ref>.
 
         <tp:rationale>
           This split between valid and invalid accounts makes it easy to
@@ -78,7 +78,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       tp:name-for-bindings="Invalid_Accounts">
       <tp:docstring>
         A list of incomplete or otherwise unusable accounts. Change
-        notification is via AccountValidityChanged.
+        notification is via
+        <tp:member-ref>AccountValidityChanged</tp:member-ref>.
       </tp:docstring>
     </property>
 
-- 
1.5.6.5




More information about the Telepathy-commits mailing list