Expand on the D-Bus docs

diff --git a/data/org.freedesktop.PolicyKit1.Authority.xml b/data/org.freedesktop.PolicyKit1.Authority.xml
index 84b22f5..ed4e57a 100644 (file)
--- a/data/org.freedesktop.PolicyKit1.Authority.xml
+++ b/data/org.freedesktop.PolicyKit1.Authority.xml
@@ -11,7 +11,10 @@
     <!-- Subject struct -->
     <annotation name="org.gtk.EggDBus.DeclareStruct" value="Subject">
       <annotation name="org.gtk.EggDBus.DocString.Summary" value="Subjects"/>
-      <annotation name="org.gtk.EggDBus.DocString" value="<para>This struct describes subjects such as UNIX processes. It is typically used to check if a given process is authorized for an action.</para><para>TODO: document required/optional key/value pairs in @subject_details.</para>"/>
+      <annotation name="org.gtk.EggDBus.DocString" value="<para>This struct describes subjects such as UNIX processes. It is typically used to check if a given process is authorized for an action.</para><para>The following kinds of subjects are known:</para>
+                  <formalpara><title>Unix Process</title><para><literal>subject_kind</literal> should be set to <literal>unix-process</literal> with keys <literal>pid</literal> (of type <literal>uint32</literal>) and <literal>start-time</literal> (of type <literal>uint64</literal>).</para></formalpara>
+                  <formalpara><title>Unix Session</title><para><literal>subject_kind</literal> should be set to <literal>unix-session</literal> with the key <literal>session-id</literal> (of type <literal>string</literal>).</para></formalpara>
+                  <formalpara><title>System Bus Name</title><para><literal>subject_kind</literal> should be set to <literal>system-bus-name</literal> with the key <literal>name</literal> (of type <literal>string</literal>).</para></formalpara>"/>
 
       <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:subject_kind">
         <annotation name="org.gtk.EggDBus.DocString" value="The type of the subject."/>
@@ -28,7 +31,11 @@
     <!-- Identity struct -->
     <annotation name="org.gtk.EggDBus.DeclareStruct" value="Identity">
       <annotation name="org.gtk.EggDBus.DocString.Summary" value="Subjects"/>
-      <annotation name="org.gtk.EggDBus.DocString" value="<para>This struct describes identities such as UNIX users and UNIX groups. It is typically used to check if a given process is authorized for an action.</para><para>TODO: document required/optional key/value pairs in @identity_details.</para>"/>
+      <annotation name="org.gtk.EggDBus.DocString" value="<para>This struct describes identities such as UNIX users and UNIX groups. It is typically used to check if a given process is authorized for an action.</para><para>The following kinds of identities are known:</para>
+                  <formalpara><title>Unix User</title><para><literal>identity_kind</literal> should be set to <literal>unix-user</literal> with key <literal>uid</literal> (of type <literal>uint32</literal>).</para></formalpara>
+                  <formalpara><title>Unix Group</title><para><literal>identity_kind</literal> should be set to <literal>unix-group</literal> with key <literal>gid</literal> (of type <literal>uint32</literal>).</para></formalpara>
+
+"/>
 
       <annotation name="org.gtk.EggDBus.Struct.Member"  value="String:identity_kind">
         <annotation name="org.gtk.EggDBus.DocString" value="Type of identity."/>
@@ -114,11 +121,11 @@
       <annotation name="org.gtk.EggDBus.DocString" value="Describes the result of calling org.freedesktop.PolicyKit1.Authority.CheckAuthorization()."/>
 
       <annotation name="org.gtk.EggDBus.Struct.Member"  value="Boolean:is_authorized">
-        <annotation name="org.gtk.EggDBus.DocString" value="#TRUE if the given #Subject is authorized for the given action."/>
+        <annotation name="org.gtk.EggDBus.DocString" value="TRUE if the given #Subject is authorized for the given action."/>
       </annotation>
 
       <annotation name="org.gtk.EggDBus.Struct.Member"  value="Boolean:is_challenge">
-        <annotation name="org.gtk.EggDBus.DocString" value="#TRUE if the given #Subject could be authorized if more information was provided, and %CheckAuthorizationFlags.AllowUserInteraction wasn't passed or no suitable authentication agent was available."/>
+        <annotation name="org.gtk.EggDBus.DocString" value="TRUE if the given #Subject could be authorized if more information was provided, and %CheckAuthorizationFlags.AllowUserInteraction wasn't passed or no suitable authentication agent was available."/>
       </annotation>
 
       <annotation name="org.gtk.EggDBus.Struct.Member"  value="Dict<String,String>:details">
@@ -164,7 +171,7 @@
     <!-- The error domain used for reporting errors -->
     <annotation name="org.gtk.EggDBus.DeclareErrorDomain" value="Error">
       <annotation name="org.gtk.EggDBus.DocString.Summary" value="Errors"/>
-      <annotation name="org.gtk.EggDBus.DocString" value="Errors that can be returned."/>
+      <annotation name="org.gtk.EggDBus.DocString" value="Errors that can be returned by various method calls."/>
 
       <annotation name="org.gtk.EggDBus.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.Failed">
         <annotation name="org.gtk.EggDBus.DocString" value="The operation failed."/>
@@ -173,10 +180,10 @@
         <annotation name="org.gtk.EggDBus.DocString" value="The operation was cancelled."/>
       </annotation>
       <annotation name="org.gtk.EggDBus.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.NotSupported">
-        <annotation name="org.gtk.EggDBus.DocString" value="Operation is not supported."/>
+        <annotation name="org.gtk.EggDBus.DocString" value="The operation is not supported."/>
       </annotation>
       <annotation name="org.gtk.EggDBus.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.NotAuthorized">
-        <annotation name="org.gtk.EggDBus.DocString" value="Not authorized to perform operation."/>
+        <annotation name="org.gtk.EggDBus.DocString" value="You are not authorized to perform the requested operation."/>
       </annotation>
 
       <!-- errors not exposed in GObject library follows here -->