[Telepathy] Proposed spec format update: struct

[Alp Toker]

Right now, structs are not marked up:

Before:
     <method name="ListTubes">
       <arg direction="out" type="a(uuusa{sv}u)">
         <tp:docstring>
          Return an array of tuples, each representing a tube, with the
          following members:

          <ul>
            <li>the tube's ID</li>
            <li>the tube's initiator</li>
            <li>the tube's type</li>
            <li>the tube's service</li>
            <li>the tube's parameters</li>
            <li>the tube's state</li>
          </ul>
         </tp:docstring>
       </arg>
     </method>

I propose to change this to:

After:
     <method name="ListTubes">
       <tp:docstring>
        Returns an array of tuples, each representing a tube.
       </tp:docstring>
       <arg direction="out" type="a(uuusa{sv}u)" tp:type="Tube_Info[]"/>
     </method>

     <tp:struct name="Tube_Info">
       <tp:docstring>
         Information representing a tube.
       </tp:docstring>
       <arg name="ID" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the tube.
         </tp:docstring>
       </arg>
       <arg name="Initiator" type="u" tp:type="Contact_Handle">
         <tp:docstring>
           The handle of the contact who initiated the tube.
         </tp:docstring>
       </arg>
       <arg name="Type" type="u" tp:type="Tube_Type">
         <tp:docstring>
           The tube type, as defined by the Tube_Type enum.
         </tp:docstring>
       </arg>
       <arg name="Service" type="s">
         <tp:docstring>
           A string representing the service that is used over the tube.
         </tp:docstring>
       </arg>
       <arg name="Parameters" type="a{sv}">
         <tp:docstring>
           The tube's properties.
         </tp:docstring>
       </arg>
       <arg name="State" type="u" tp:type="Tube_State">
         <tp:docstring>
           The tube's state.
         </tp:docstring>
       </arg>
     </tp:struct>


Hence we can formalise a common pattern in the Telepathy spec, 
eliminating much redundancy and potentially increasing code re-use in 
generated proxies:

Before:
     <signal name="NewTube">
       <tp:docstring>
         Emitted when a tube is created.
       </tp:docstring>
       <arg name="id" type="u" tp:type="Tube_ID">
         <tp:docstring>
           The ID of the new tube.
         </tp:docstring>
       </arg>
       <arg name="initiator" type="u" tp:type="Contact_Handle">
         <tp:docstring>
           The handle of the contact who initiated the tube.
         </tp:docstring>
       </arg>
       <arg name="type" type="u" tp:type="Tube_Type">
         <tp:docstring>
           The tube type, as defined by the Tube_Type enum.
         </tp:docstring>
       </arg>
       <arg name="service" type="s">
         <tp:docstring>
           A string representing the service that will be used over the 
tube.
         </tp:docstring>
       </arg>
       <arg name="parameters" type="a{sv}">
         <tp:docstring>
           The new tube's properties.
         </tp:docstring>
       </arg>
       <arg name="state" type="u" tp:type="Tube_State">
         <tp:docstring>
           The new tube's state.
         </tp:docstring>
       </arg>
     </signal>

After:
    <signal name="NewTube">
       <tp:docstring>
         Emitted when a tube is created.
       </tp:docstring>
       <tp:args name="new_tube_info" tp:type="Tube_Info">
         <tp:docstring>
           Information about the new tube.
         </tp:docstring>
       </arg>
     </signal>

The new element and attribute here are:

tp:struct
   Represents a D-Bus structure. Note that the "name" attribute in args 
of a tp:struct is now in Telepathy_Camel_Case, ready for translation 
into the appropriate format.

tp:args
   A reference to a tp:struct, from which the args will be used directly 
as args for the method/signal being specified. This is only necessary 
because struct re-use was overlooked when the Telepathy spec was 
conceived. We now have a means to patch this up without breaking API.