PolicyKit: Branch 'master'
David Zeuthen
david at kemper.freedesktop.org
Thu Feb 5 12:08:19 PST 2009
data/org.freedesktop.PolicyKit1.AuthenticationAgent.xml | 2
data/org.freedesktop.PolicyKit1.Authority.xml | 75 +++++++++-------
data/org.freedesktop.PolicyKit1.AuthorityManager.xml | 25 ++---
3 files changed, 60 insertions(+), 42 deletions(-)
New commits:
commit 9be488b06aabe48a91e67ed7b0cc101edf0b01c3
Author: David Zeuthen <davidz at redhat.com>
Date: Thu Feb 5 15:06:30 2009 -0500
fix up the D-Bus docs somewhat
diff --git a/data/org.freedesktop.PolicyKit1.AuthenticationAgent.xml b/data/org.freedesktop.PolicyKit1.AuthenticationAgent.xml
index 9ea9a7a..9b2a5d5 100644
--- a/data/org.freedesktop.PolicyKit1.AuthenticationAgent.xml
+++ b/data/org.freedesktop.PolicyKit1.AuthenticationAgent.xml
@@ -19,7 +19,7 @@
</arg>
<arg name="identities" direction="in" type="a(sa{sv})">
- <annotation name="org.gtk.EggDBus.DocString" value="A list of identities of that the user can use for authentication."/>
+ <annotation name="org.gtk.EggDBus.DocString" value="A list of #Identity structs that the user can use for authentication."/>
</arg>
</method>
diff --git a/data/org.freedesktop.PolicyKit1.Authority.xml b/data/org.freedesktop.PolicyKit1.Authority.xml
index 06018ee..e0eb900 100644
--- a/data/org.freedesktop.PolicyKit1.Authority.xml
+++ b/data/org.freedesktop.PolicyKit1.Authority.xml
@@ -8,28 +8,30 @@
<!-- 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.Struct.Member" value="s:subject_kind">
- <annotation name="org.gtk.EggDBus.DocString" value="Kind of subject"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The type of the subject."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="a{sv}:subject_details">
- <annotation name="org.gtk.EggDBus.DocString" value="Details about the subject"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Details about the subject. Depending of the value of @subject_kind, a set of well-defined key/value pairs are guaranteed to be available."/>
</annotation>
- <!-- TODO: document values in hash map for each subject type-->
-
</annotation>
<!-- 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.Struct.Member" value="s:identity_kind">
- <annotation name="org.gtk.EggDBus.DocString" value="Kind of identity"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Type of identity."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="a{sv}:identity_details">
- <annotation name="org.gtk.EggDBus.DocString" value="Details about the identity"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Details about the identity. Depending of the value of @identity_kind, a set of well-defined key/value pairs are guaranteed to be available."/>
</annotation>
<!-- TODO: document values in hash map for each identity type-->
@@ -38,77 +40,87 @@
<!-- ActionDescription struct -->
<annotation name="org.gtk.EggDBus.DeclareStruct" value="ActionDescription">
+ <annotation name="org.gtk.EggDBus.DocString.Summary" value="Actions"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="This struct describes actions registered with the PolicyKit daemon."/>
<annotation name="org.gtk.EggDBus.Struct.Member" value="s:action_id">
- <annotation name="org.gtk.EggDBus.DocString" value="Action Identifier"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Action Identifier."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="s:description">
- <annotation name="org.gtk.EggDBus.DocString" value="Action Description"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Localized description of the action."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="s:message">
- <annotation name="org.gtk.EggDBus.DocString" value="Action Message"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Localized message to be displayed when making the user authenticate for an action."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="s:vendor_name">
- <annotation name="org.gtk.EggDBus.DocString" value="Vendor Name"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Name of the provider of the action or the empty string."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="s:vendor_url">
- <annotation name="org.gtk.EggDBus.DocString" value="Vendor URL"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="A URL pointing to a place with more information about the action or the empty string."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="s:icon_name">
- <annotation name="org.gtk.EggDBus.DocString" value="Icon Name"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The themed icon describing the action or the empty string if no icon is set."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="i:implicit_any">
<annotation name="org.gtk.EggDBus.EnumType" value="ImplicitAuthorization"/>
- <annotation name="org.gtk.EggDBus.DocString" value="Defaults for any kind of subject"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="A value from the #ImplicitAuthorization enumeration for implicit authorizations that apply to any #Subject."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="i:implicit_inactive">
<annotation name="org.gtk.EggDBus.EnumType" value="ImplicitAuthorization"/>
- <annotation name="org.gtk.EggDBus.DocString" value="Defaults for subjects in local inactive sessions"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="A value from the #ImplicitAuthorization enumeration for implicit authorizations that apply any #Subject in an inactive user session on the local console."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="i:implicit_active">
<annotation name="org.gtk.EggDBus.EnumType" value="ImplicitAuthorization"/>
- <annotation name="org.gtk.EggDBus.DocString" value="Defaults for subjects in local active sessions"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="A value from the #ImplicitAuthorization enumeration for implicit authorizations that apply any #Subject in an active user session on the local console."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="a{ss}:annotations">
- <annotation name="org.gtk.EggDBus.DocString" value="Annotations"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Annotations for the action."/>
</annotation>
</annotation>
<!-- Flags used for checking authorizations -->
<annotation name="org.gtk.EggDBus.DeclareFlags" value="CheckAuthorizationFlags">
+ <annotation name="org.gtk.EggDBus.DocString.Summary" value="Flags used when checking authorizations"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Flags used in the org.freedesktop.PolicyKit1.Authority.CheckAuthorization() method."/>
+
<annotation name="org.gtk.EggDBus.Flags.Member" value="AllowUserInteraction">
- <annotation name="org.gtk.EggDBus.DocString" value="If the subject can obtain the authorization through authentication, and an authentication agent is available, then attempt to do so. Note, this means that the #CheckAuthorization() method is likely to block for a long time."/>
+ <annotation name="org.gtk.EggDBus.DocString" value="If the #Subject can obtain the authorization through authentication, and an authentication agent is available, then attempt to do so. Note, this means that the org.freedesktop.PolicyKit1.Authority.CheckAuthorization() method will block while the user is being asked to authenticate."/>
</annotation>
</annotation>
<!-- An enumeration for results when checking for an authorization -->
<annotation name="org.gtk.EggDBus.DeclareEnum" value="AuthorizationResult">
+ <annotation name="org.gtk.EggDBus.DocString.Summary" value="Possible results for checking authorizations"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Possible results that the org.freedesktop.PolicyKit1.Authority.CheckAuthorization() method can return."/>
+
<annotation name="org.gtk.EggDBus.Enum.Member" value="NotAuthorized">
- <annotation name="org.gtk.EggDBus.DocString" value="The subject is not authorized for the specified action"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The given #Subject is not authorized for the specified action."/>
</annotation>
<annotation name="org.gtk.EggDBus.Enum.Member" value="Authorized">
- <annotation name="org.gtk.EggDBus.DocString" value="The subject is authorized for the specified action"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The given #Subject is authorized for the specified action."/>
</annotation>
<annotation name="org.gtk.EggDBus.Enum.Member" value="Challenge">
- <annotation name="org.gtk.EggDBus.DocString" value="The subject is authorized if more information is provided"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The given #Subject is authorized if more information is provided."/>
</annotation>
</annotation>
<!-- An enumeration for implicit authorizations -->
<annotation name="org.gtk.EggDBus.DeclareEnum" value="ImplicitAuthorization">
+ <annotation name="org.gtk.EggDBus.DocString.Summary" value="Implicit authorizations"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="An enumeration for granting implicit authorizations."/>
<annotation name="org.gtk.EggDBus.Enum.Member" value="NotAuthorized">
- <annotation name="org.gtk.EggDBus.DocString" value="Subject is not authorized."/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The #Subject is not authorized."/>
</annotation>
<annotation name="org.gtk.EggDBus.Enum.Member" value="AuthenticationRequired">
@@ -128,21 +140,24 @@
</annotation>
<annotation name="org.gtk.EggDBus.Enum.Member" value="Authorized">
- <annotation name="org.gtk.EggDBus.DocString" value="The subject is authorized"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The subject is authorized."/>
</annotation>
</annotation>
<!-- 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.ErrorDomain.Member" value="org.freedesktop.PolicyKit1.Error.Failed">
- <annotation name="org.gtk.EggDBus.DocString" value="The operation failed"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The operation failed."/>
</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="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="Not authorized to perform operation."/>
</annotation>
</annotation>
@@ -154,7 +169,7 @@
</arg>
<arg name="action_descriptions" direction="out" type="a(ssssssiiia{ss})">
- <annotation name="org.gtk.EggDBus.DocString" value="An array of action description structs."/>
+ <annotation name="org.gtk.EggDBus.DocString" value="An array of #ActionDescription structs."/>
<annotation name="org.gtk.EggDBus.StructType" value="ActionDescription"/>
</arg>
</method>
@@ -163,7 +178,7 @@
<annotation name="org.gtk.EggDBus.DocString" value="Checks if @subject is authorized to perform the action with identifier @action_id."/>
<arg name="subject" direction="in" type="(sa{sv})">
- <annotation name="org.gtk.EggDBus.DocString" value="The subject in question."/>
+ <annotation name="org.gtk.EggDBus.DocString" value="A #Subject struct."/>
<annotation name="org.gtk.EggDBus.StructType" value="Subject"/>
</arg>
@@ -177,7 +192,7 @@
</arg>
<arg name="result" direction="out" type="i">
- <annotation name="org.gtk.EggDBus.DocString" value="The result of the authorization check."/>
+ <annotation name="org.gtk.EggDBus.DocString" value="A value from #AuthorizationResult enumeration."/>
<annotation name="org.gtk.EggDBus.EnumType" value="AuthorizationResult"/>
</arg>
</method>
@@ -207,12 +222,12 @@
<arg name="identity" direction="in" type="(sa{sv})">
<annotation name="org.gtk.EggDBus.StructType" value="Identity"/>
- <annotation name="org.gtk.EggDBus.DocString" value="The identity that was authenticated."/>
+ <annotation name="org.gtk.EggDBus.DocString" value="A #Identity struct describing what identity was authenticated."/>
</arg>
</method>
<signal name="Changed">
- <annotation name="org.gtk.EggDBus.DocString" value="Emitted when actions and/or authorizations change"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="This signal is emitted when actions and/or authorizations change"/>
</signal>
</interface>
diff --git a/data/org.freedesktop.PolicyKit1.AuthorityManager.xml b/data/org.freedesktop.PolicyKit1.AuthorityManager.xml
index 44211e3..d859e0a 100644
--- a/data/org.freedesktop.PolicyKit1.AuthorityManager.xml
+++ b/data/org.freedesktop.PolicyKit1.AuthorityManager.xml
@@ -8,17 +8,20 @@
<!-- Authorization struct -->
<annotation name="org.gtk.EggDBus.DeclareStruct" value="Authorization">
+ <annotation name="org.gtk.EggDBus.DocString.Summary" value="Authorizations"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="This struct describes an authorization belonging to an #Identity."/>
+
<annotation name="org.gtk.EggDBus.Struct.Member" value="s:action_id">
- <annotation name="org.gtk.EggDBus.DocString" value="Identifier for the action the authorization is for"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Identifier for the action the authorization is for."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="(sa{sv}):subject">
<annotation name="org.gtk.EggDBus.StructType" value="Subject"/>
- <annotation name="org.gtk.EggDBus.DocString" value="Subject that the authorization applies to"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The #Subject that the authorization applies to."/>
</annotation>
<annotation name="org.gtk.EggDBus.Struct.Member" value="b:is_negative">
- <annotation name="org.gtk.EggDBus.DocString" value="Whether the authorization is negative"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="Whether the authorization is negative."/>
</annotation>
</annotation>
@@ -26,7 +29,7 @@
<annotation name="org.gtk.EggDBus.DocString" value="Enumerate all users known to the authority."/>
<arg name="users" direction="out" type="a(sa{sv})">
- <annotation name="org.gtk.EggDBus.DocString" value="An array of identities."/>
+ <annotation name="org.gtk.EggDBus.DocString" value="An array of #Identity structs."/>
<annotation name="org.gtk.EggDBus.StructType" value="Identity"/>
</arg>
</method>
@@ -35,7 +38,7 @@
<annotation name="org.gtk.EggDBus.DocString" value="Enumerate all groups known to the authority."/>
<arg name="groups" direction="out" type="a(sa{sv})">
- <annotation name="org.gtk.EggDBus.DocString" value="An array of identities."/>
+ <annotation name="org.gtk.EggDBus.DocString" value="An array of #Identity structs."/>
<annotation name="org.gtk.EggDBus.StructType" value="Identity"/>
</arg>
</method>
@@ -44,11 +47,11 @@
<annotation name="org.gtk.EggDBus.DocString" value="Add an authorization to @identity."/>
<arg name="identity" direction="in" type="(sa{sv})">
- <annotation name="org.gtk.EggDBus.DocString" value="The identity to add @authorization to"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The #Identity to add @authorization to."/>
<annotation name="org.gtk.EggDBus.StructType" value="Identity"/>
</arg>
<arg name="authorization" direction="in" type="(s(sa{sv})b)">
- <annotation name="org.gtk.EggDBus.DocString" value="The authorization to add for @identity"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The #Authorization to add to @identity."/>
<annotation name="org.gtk.EggDBus.StructType" value="Authorization"/>
</arg>
</method>
@@ -57,11 +60,11 @@
<annotation name="org.gtk.EggDBus.DocString" value="Remove an authorization from @identity."/>
<arg name="identity" direction="in" type="(sa{sv})">
- <annotation name="org.gtk.EggDBus.DocString" value="The identity to remove @authorization from"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The #Identity to remove @authorization from."/>
<annotation name="org.gtk.EggDBus.StructType" value="Identity"/>
</arg>
<arg name="authorization" direction="in" type="(s(sa{sv})b)">
- <annotation name="org.gtk.EggDBus.DocString" value="The authorization to remove from @identity"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="The #Authorization to remove from @identity."/>
<annotation name="org.gtk.EggDBus.StructType" value="Authorization"/>
</arg>
</method>
@@ -71,11 +74,11 @@
<arg name="identity" direction="in" type="(sa{sv})">
<annotation name="org.gtk.EggDBus.StructType" value="Identity"/>
- <annotation name="org.gtk.EggDBus.DocString" value="The identity to enumerate authorizations for"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="An #Identity to enumerate authorizations for."/>
</arg>
<arg name="authorizations" direction="out" type="a(s(sa{sv})b)">
<annotation name="org.gtk.EggDBus.StructType" value="Authorization"/>
- <annotation name="org.gtk.EggDBus.DocString" value="An array of authorizations for @identity"/>
+ <annotation name="org.gtk.EggDBus.DocString" value="An array of #Authorization structs for @identity."/>
</arg>
</method>
More information about the hal-commit
mailing list