From 878f9b694c99c39cecd2cee0f33821659786772b Mon Sep 17 00:00:00 2001
From: Michael Leupold <lemma@confuego.org>
Date: Sat, 25 Sep 2010 22:21:16 +0200
Subject: Have a try at a better explanation of the terms Property and
 Attribute in the context of CreateCollection and CreateItem.

---
 secret-service/org.freedesktop.Secrets.xml | 45 +++++++++++++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

(limited to 'secret-service')

diff --git a/secret-service/org.freedesktop.Secrets.xml b/secret-service/org.freedesktop.Secrets.xml
index 73c275b..da58b7f 100644
--- a/secret-service/org.freedesktop.Secrets.xml
+++ b/secret-service/org.freedesktop.Secrets.xml
@@ -102,7 +102,21 @@
             <method name="CreateCollection">
                 <tp:docstring>Create a new collection with the specified properties.</tp:docstring>
                 <arg name="properties" type="a{sv}" direction="in">
-                    <tp:docstring>Properties for the new collection.</tp:docstring>
+                    <tp:docstring xmlns:docbook="http://docbook.org/ns/docbook">
+                        <para>
+                            Properties for the new collection. This allows setting the new collection's
+                            properties upon its creation. All READWRITE properties of the Collection
+                            interface are useable.
+                            <example>
+                                <title>Example for properties</title>
+                                <programlisting>
+<![CDATA[
+properties = { "Label": "MyCollection" }
+]]>
+                                </programlisting>
+                            </example>
+                        </para>
+                    </tp:docstring>
                 </arg>
                 <arg name="collection" type="o" direction="out">
                     <tp:docstring>The new collection object, or '/' if prompting is necessary.</tp:docstring>
@@ -264,6 +278,35 @@
                 <tp:docstring>Create an item with the given attributes, secret and label. If replace is set, then it replaces an item already present with the same values for the attributes.</tp:docstring>
                 <arg name="properties" type="a{sv}" direction="in">
                     <tp:docstring>The properties for the new item.</tp:docstring>
+                    <tp:docstring xmlns:docbook="http://docbook.org/ns/docbook">
+                        <para>
+                            Properties for the new item. This allows setting the new item's
+                            properties upon its creation. All READWRITE properties of the Item
+                            interface are useable.
+                            <example>
+                                <title>Example for properties</title>
+                                <programlisting>
+<![CDATA[
+properties = {
+               "Label": "MyItem",
+               "Attributes": {
+                               "Attribute1": "Value1",
+                               "Attribute2": "Value2"
+                             }
+             }
+]]>
+                                </programlisting>
+                            </example>
+                            <note>
+                                <para>
+                                    Please note that there is a distinction between the terms
+                                    <emphasis>Property</emphasis>, which refers to a D-Bus properties
+                                    of an object, and <emphasis>Attribute</emphasis>, which refers to one
+                                    of a secret item's string-valued attributes.
+                                </para>
+                            </note>
+                        </para>
+                    </tp:docstring>
                 </arg>
                 <arg name="secret" type="(oayay)" tp:type="Secret" direction="in">
                     <tp:docstring>The secret to store in the item, encoded with the included session.</tp:docstring>
-- 
cgit v1.2.3-54-g00ecf