[telepathy-spec/master] Stream.I.Media: attempt to fix spec-lint
Simon McVittie
simon.mcvittie at collabora.co.uk
Tue Dec 1 05:41:38 PST 2009
* editorial changes
* use conventional case
* ask for rationale
* attempt to cross-reference more
* declare Transport to be immutable
* give LocalCredentials a struct type so telepathy-qt4 can bind it
---
spec/Call_Stream_Interface_Media.xml | 140 +++++++++++++++++++++++++---------
1 files changed, 104 insertions(+), 36 deletions(-)
diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml
index 5224dd1..e58712d 100644
--- a/spec/Call_Stream_Interface_Media.xml
+++ b/spec/Call_Stream_Interface_Media.xml
@@ -26,70 +26,95 @@
<tp:requires interface="org.freedesktop.Telepathy.Call.Stream"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ [FIXME]
</tp:docstring>
<tp:method name="SetCredentials" tp:name-for-bindings="Set_Credentials">
<tp:docstring>
Used to set the username fragment and password for streams that have
- global credentials
+ global credentials.
+
+ <tp:rationale>
+ [FIXME: rationale?]
+ </tp:rationale>
</tp:docstring>
- <arg name="username" type="s" direction="in"/>
- <arg name="password" type="s" direction="in" />
+ <arg name="Username" type="s" direction="in"/>
+ <arg name="Password" type="s" direction="in" />
</tp:method>
<tp:mapping name="Candidate_Info">
- <tp:member name="key" type="s"/>
- <tp:member name="value" type="v"/>
- <tp:docstring>
- Extra information about the candidate. Allowed and Mandatory keys
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ Extra information about the candidate. Allowed and mandatory keys
depend on the transport protocol used. The following keys are commenly
used:
<dl>
- <dt> Type (u)</dt>
- <dd> type of candidate (host, srflx, prflx, relay)</dd>
+ <dt>Type (u)</dt>
+ <dd>type of candidate (host, srflx, prflx, relay)</dd>
- <dt> Foundation (s)</dt>
- <dd> the foundation of this candiate</dd>
+ <dt>Foundation (s)</dt>
+ <dd>the foundation of this candiate</dd>
- <dt> Protocol (u) </dt>
- <dd> Underlying protocol of the candidate (udp, tcp) </dd>
+ <dt>Protocol (u) </dt>
+ <dd>Underlying protocol of the candidate (udp, tcp) </dd>
- <dt> Priority (u) </dt>
- <dd> Priority of the candidate </dd>
+ <dt>Priority (u) </dt>
+ <dd>Priority of the candidate </dd>
- <dt> BaseIP (u) </dt>
- <dd> Base IP of this candidate </dd>
+ <dt>BaseIP (u) </dt>
+ <dd>Base IP of this candidate </dd>
- <dt> Username (s) </dt>
- <dd> Username of this candidate
+ <dt>Username (s) </dt>
+ <dd>Username of this candidate
(only if credentials are per candidate)</dd>
- <dt> Password (s) </dt>
- <dd> Password of this candidate
+ <dt>Password (s) </dt>
+ <dd>Password of this candidate
(only if credentials are per candidate)</dd>
- <dt> RawUDPFallback (b) </dt>
- <dd> Indicate whether this candidate may be used to provide a UDP
+ <dt>RawUDPFallback (b) </dt>
+ <dd>Indicate whether this candidate may be used to provide a UDP
fallback</dd>
-
</dl>
</tp:docstring>
+ <tp:member name="Key" type="s">
+ <tp:docstring>One of the well-known keys documented here, or an
+ implementation-specific key</tp:docstring>
+ </tp:member>
+ <tp:member name="Value" type="v">
+ <tp:docstring>The value corresponding to that key</tp:docstring>
+ </tp:member>
</tp:mapping>
<tp:struct name="Candidate" array-name="Candidate_List">
<tp:docstring>A Stream Candidate</tp:docstring>
- <tp:member name="component" type="u" />
- <tp:member name="ip" type="s" />
- <tp:member name="port" type="q" />
- <tp:member name="info" type="a{sv}" tp:type="Candidate_Info">
+ <tp:member name="Component" type="u">
+ <tp:docstring>The component number</tp:docstring>
+ </tp:member>
+ <tp:member name="IP" type="s">
+ <tp:docstring>The IP address to use</tp:docstring>
+ </tp:member>
+ <tp:member name="Port" type="q">
+ <tp:docstring>The port number to use</tp:docstring>
+ </tp:member>
+ <tp:member name="Info" type="a{sv}" tp:type="Candidate_Info">
+ <tp:docstring>Additional information about the candidate</tp:docstring>
</tp:member>
-
</tp:struct>
<method name="AddCandidates" tp:name-for-bindings="Add_Candidates">
+ <tp:docstring>
+ Add candidates to <tp:member-ref>LocalCandidates</tp:member-ref>
+ and signal them to the remote contact(s).
+ </tp:docstring>
+
<arg name="candidates" direction="in"
- type="a(usqa{sv})" tp:type="Candidate[]" />
+ type="a(usqa{sv})" tp:type="Candidate[]">
+ <tp:docstring>
+ Candidates to be appended to
+ <tp:member-ref>LocalCandidates</tp:member-ref>
+ </tp:docstring>
+ </arg>
</method>
<method name="CandidatesPrepared"
@@ -97,6 +122,10 @@
<tp:docstring>
This indicates to the CM that the initial batch of candidates has been
added.
+
+ <tp:rationale>
+ [FIXME: rationale]
+ </tp:rationale>
</tp:docstring>
</method>
@@ -158,26 +187,65 @@
<property name="Transport" tp:name-for-bindings="Transport"
type="u" tp:type="Stream_Transport_Type" access="read">
+ <tp:docstring>
+ The transport for this stream. This property is immutable.
+ </tp:docstring>
</property>
<property name="LocalCandidates" tp:name-for-bindings="Local_Candidates"
type="a(usqa{sv})" tp:type="Candidate[]" access="read">
+ <tp:docstring>
+ [FIXME]. Change notification is via
+ <tp:member-ref>LocalCandidatesAdded</tp:member-ref>.
+ </tp:docstring>
</property>
<signal name="LocalCandidatesAdded"
- tp:name-for-bindings="Local_Candidates_Added">
+ tp:name-for-bindings="Local_Candidates_Added">
+ <tp:docstring>
+ Emitted when local candidates are added to
+ <tp:member-ref>LocalCandidates</tp:member-ref>.
+ </tp:docstring>
+
<arg name="Candidates"
- type="a(usqa{sv})" tp:type="Candidate[]"/>
+ type="a(usqa{sv})" tp:type="Candidate[]">
+ <tp:docstring>
+ Candidates that have been appended to
+ <tp:member-ref>LocalCandidates</tp:member-ref>
+ </tp:docstring>
+ </arg>
</signal>
+ <tp:struct name="Stream_Credentials">
+ <tp:docstring>A username/password pair.</tp:docstring>
+
+ <tp:member name="Username" type="s">
+ <tp:docstring>The username</tp:docstring>
+ </tp:member>
+
+ <tp:member name="Password" type="s">
+ <tp:docstring>The password</tp:docstring>
+ </tp:member>
+ </tp:struct>
+
<property name="LocalCredentials" tp:name-for-bindings="Local_Credentials"
- type="(ss)" access="read">
+ type="(ss)" tp:type="Stream_Credentials" access="read">
+ <tp:docstring>
+ [FIXME]. Change notification is via
+ <tp:member-ref>LocalCredentialsChanged</tp:member-ref>.
+ </tp:docstring>
+
</property>
<signal name="LocalCredentialsSet"
- tp:name-for-bindings="LocalCredentialsSet">
- <arg name="username" type="s" />
- <arg name="password" type="s" />
+ tp:name-for-bindings="Local_Credentials_Set">
+ <tp:docstring>
+ Emitted when the value of
+ <tp:member-ref>LocalCredentials</tp:member-ref> changes.
+ </tp:docstring>
+
+ <arg name="Username" type="s" />
+ <arg name="Password" type="s" />
</signal>
<property name="STUNServers" tp:name-for-bindings="STUN_Servers"
--
1.5.6.5
More information about the telepathy-commits
mailing list