[Telepathy-commits] [telepathy-spec/master] Avatars: add cross-references; fix "AvatarChanged"

[Will Thompson]

---
 spec/Connection_Interface_Avatars.xml |   41 ++++++++++++++++++++-------------
 1 files changed, 25 insertions(+), 16 deletions(-)

diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml
index 76b85f3..692c101 100644
--- a/spec/Connection_Interface_Avatars.xml
+++ b/spec/Connection_Interface_Avatars.xml
@@ -43,7 +43,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         Emitted when the avatar for a contact has been updated, or first
         discovered on this connection. If the token differs from the token
         associated with the client's cached avatar for this contact, the new
-        avatar should be requested with RequestAvatars.
+        avatar should be requested with
+        <tp:member-ref>RequestAvatars</tp:member-ref>.
       </tp:docstring>
     </signal>
     <signal name="AvatarRetrieved" tp:name-for-bindings="Avatar_Retrieved">
@@ -130,7 +131,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         Get the unique tokens for all of the given contacts' avatars.
 
         Using this method in new Telepathy clients is deprecated; use
-        GetKnownAvatarTokens instead.
+        <tp:member-ref>GetKnownAvatarTokens</tp:member-ref> instead.
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -213,11 +214,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:docstring>
       </arg>
       <tp:docstring>
-        Request avatars for a number of contacts. The AvatarRetrieved signal
-        is emitted for each avatar retrieved. If the handles are valid but
-        retrieving an avatar fails (for any reason, including the contact not
-        having an avatar) the AvatarRetrieved signal is not emitted for that
-        contact.
+        Request avatars for a number of contacts. The
+        <tp:member-ref>AvatarRetrieved</tp:member-ref> signal is emitted for
+        each avatar retrieved. If the handles are valid but retrieving an
+        avatar fails (for any reason, including the contact not having an
+        avatar) the AvatarRetrieved signal is not emitted for that contact.
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -242,7 +243,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </arg>
       <tp:docstring>
         Set a new avatar image for this connection. The avatar image must
-        respect the requirements obtained by GetAvatarRequirements.
+        respect the requirements obtained by
+        <tp:member-ref>GetAvatarRequirements</tp:member-ref>.
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -273,21 +275,27 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     a changed token implies the contact's avatar has changed, but the strings
     should otherwise be considered opaque by clients.</p>
 
-    <p>A client should use GetKnownAvatarTokens to request the tokens for the
+    <p>A client should use <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>
+    to request the tokens for the
     avatars of all the contacts it is interested in when it connects. The
-    avatars can then be requested using RequestAvatars for the contacts.
-    Clients should bind to the AvatarChanged signal and request a new copy of
+    avatars can then be requested using
+    <tp:member-ref>RequestAvatars</tp:member-ref> for the contacts.  Clients
+    should bind to the <tp:member-ref>AvatarUpdated</tp:member-ref> signal and
+    request a new copy of
     the avatar when a contacts' avatar token changes. Clients should cache the
     token and data of each contact's avatar between connections, to avoid
     repeatedly retrieving the same avatar.</p>
 
-    <p>To publish an avatar, a client should use SetAvatar to provide an image
-    which meets the requirements returned by the GetAvatarRequirements
+    <p>To publish an avatar, a client should use
+    <tp:member-ref>SetAvatar</tp:member-ref> to provide an image which meets
+    the requirements returned by the
+    <tp:member-ref>GetAvatarRequirements</tp:member-ref>
     function. On some protocols the avatar is stored on the server, so setting
     the avatar is persistent, but on others it is transferred via a peer to
     peer mechanism, so needs to be set every connection. Hence, on every
     connection, clients should inspect the avatar token of the connection's
-    self handle using GetKnownAvatarTokens; if the self handle is not in the
+    self handle using <tp:member-ref>GetKnownAvatarTokens</tp:member-ref>; if
+    the self handle is not in the
     returned map, the client should re-set the avatar. If the self handle's
     avatar token is known, but the avatar has been changed locally since the
     last connection, the client should upload the new avatar; if the avatar has
@@ -295,8 +303,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     server if its token differs from the that of the local avatar.</p>
 
     <p>To remove the published avatar on protocols which have persistent avatars,
-    a client should use the ClearAvatar method. This method can safely be used
-    even if there is no avatar for this connection.</p>
+    a client should use the <tp:member-ref>ClearAvatar</tp:member-ref> method.
+    This method can safely be used even if there is no avatar for this
+    connection.</p>
     </tp:docstring>
   </interface>
 </node>
-- 
1.5.6.5