Precise Secret Service API in auth.texi (Bug#29575)

* doc/misc/auth.texi (Secret Service API): Item labels are not
unique.  Document this.  (Bug#29575)

1 files changed, 26 insertions, 13 deletions

diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index 9cf16d8ed4f..fcbc83ead5b 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -348,25 +348,36 @@ Returns all the item labels of @var{collection} as a list.
 
 @defun secrets-create-item collection item password &rest attributes
 This function creates a new item in @var{collection} with label
-@var{item} and password @var{password}.  @var{attributes} are
-key-value pairs set for the created item.  The keys are keyword
-symbols, starting with a colon.  Example:
+@var{item} and password @var{password}.  The label @var{item} does not
+have to be unique in @var{collection}.  @var{attributes} are key-value
+pairs set for the created item.  The keys are keyword symbols,
+starting with a colon.  Example:
 
 @example
-;;; The session "session", the label is "my item"
-;;; and the secret (password) is "geheim"
+;;; The session is "session", the label is "my item"
+;;; and the secret (password) is "geheim".
 (secrets-create-item "session" "my item" "geheim"
  :method "sudo" :user "joe" :host "remote-host")
 @end example
+
+The key @code{:xdg:schema} determines the scope of the item to be
+generated, i.e.@: for which applications the item is intended for.
+This is just a string like "org.freedesktop.NetworkManager.Mobile" or
+"org.gnome.OnlineAccounts", the other required keys are determined by
+this.  If no @code{:xdg:schema} is given,
+"org.freedesktop.Secret.Generic" is used by default.
 @end defun
 
 @defun secrets-get-secret collection item
-Return the secret of item labeled @var{item} in @var{collection}.
-If there is no such item, return @code{nil}.
+Return the secret of item labeled @var{item} in @var{collection}.  If
+there are several items labeled @var{item}, it is undefined which one
+is returned.  If there is no such item, return @code{nil}.
 @end defun
 
 @defun secrets-delete-item collection item
-This function deletes item @var{item} in @var{collection}.
+This function deletes item @var{item} in @var{collection}.  If there
+are several items labeled @var{item}, it is undefined which one is
+deleted.
 @end defun
 
 The lookup attributes, which are specified during creation of a
@@ -376,18 +387,20 @@ from a given secret item and they can be used for searching of items.
 
 @defun secrets-get-attribute collection item attribute
 Returns the value of key @var{attribute} of item labeled @var{item} in
-@var{collection}.  If there is no such item, or the item doesn't own
-this key, the function returns @code{nil}.
+@var{collection}.  If there are several items labeled @var{item}, it
+is undefined which one is returned.  If there is no such item, or the
+item doesn't own this key, the function returns @code{nil}.
 @end defun
 
 @defun secrets-get-attributes collection item
 Return the lookup attributes of item labeled @var{item} in
-@var{collection}.  If there is no such item, or the item has no
-attributes, it returns @code{nil}.  Example:
+@var{collection}.  If there are several items labeled @var{item}, it
+is undefined which one is returned.  If there is no such item, or the
+item has no attributes, it returns @code{nil}.  Example:
 
 @example
 (secrets-get-attributes "session" "my item")
-     @result{} ((:user . "joe") (:host ."remote-host"))
+     @result{} ((:user . "joe") (:host . "remote-host"))
 @end example
 @end defun