[Emacs-diffs] /srv/bzr/emacs/trunk r107767: auth.texi small edits

[Glenn Morris]

------------------------------------------------------------
revno: 107767
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2012-04-04 16:36:33 -0400
message:
  auth.texi small edits
  
  * doc/misc/auth.texi (Secret Service API): Copyedits.
  (Help for developers): Fill in some missing function doc-strings.
modified:
  doc/misc/ChangeLog
  doc/misc/auth.texi

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-04-04 15:28:57 +0000
+++ b/doc/misc/ChangeLog        2012-04-04 20:36:33 +0000
@@ -1,3 +1,8 @@
+2012-04-04  Glenn Morris  <address@hidden>
+
+       * auth.texi (Secret Service API): Copyedits.
+       (Help for developers): Fill in some missing function doc-strings.
+
 2012-04-04  Michael Albinus  <address@hidden>
 
        * auth.texi (Secret Service API): Add the missing text.

=== modified file 'doc/misc/auth.texi'
--- a/doc/misc/auth.texi        2012-04-04 15:28:57 +0000
+++ b/doc/misc/auth.texi        2012-04-04 20:36:33 +0000
@@ -233,9 +233,9 @@
 Implementations of compliant daemons are the GNOME Keyring and the KDE
 Wallet.
 
-Although the usage of the client library secrets.el is hidden in Emacs
-via the auth-source library, its functionality can be used also
-directly in other packages.
+The auth-source library uses the @file{secrets.el} library as an
+interface to this feature.  You can also use that library in other
+packages.
 
 @defvar secrets-enabled
 After loading @file{secrets.el}, a address@hidden value of this
@@ -244,7 +244,7 @@
 @end defvar
 
 @deffn Command secrets-show-secrets
-All collections, items, and their attributes are inspected by this command.
+This command inspects all collections, items, and their attributes.
 @end deffn
 
 The atomic objects to be managed by the Secret Service API are
@@ -260,9 +260,9 @@
 
 A collection can have an alias name.  The use case for this is to
 set the alias @samp{"default"} for a given collection, making it
-transparent for clients, which collection is used.  Other aliases
+transparent to clients as to which collection is used.  Other aliases
 are not supported (yet).  Since an alias is visible to all
-applications, this setting shall be performed with care.
+applications, this setting should be performed with care.
 
 @defun secrets-list-collections
 This function returns a list of collection names.
@@ -281,15 +281,15 @@
 Collections can be created and deleted by the functions
 @code{secrets-create-collection} and @code{secrets-delete-collection}.
 Usually, this is not applied from within Emacs.  Common collections,
-like @samp{"login"}, shall never be deleted.
+like @samp{"login"}, should never be deleted.
 
 There exists a special collection called @samp{"session"}, which has
 the lifetime of the corresponding client session (aka Emacs's
 lifetime).  It is created automatically when Emacs uses the Secret
 Service interface, and it is deleted when Emacs is killed.  Therefore,
 it can be used to store and retrieve secret items temporarily.  This
-shall be preferred over creation of a persistent collection, when the
-information shall not live longer than Emacs.  The session collection
+should be preferred over creation of a persistent collection, when the
+information should not live longer than Emacs.  The session collection
 can be addressed either by the string @samp{"session"}, or by
 @code{nil}, whenever a collection parameter is needed in the following
 functions.
@@ -305,7 +305,7 @@
 
 @defun secrets-create-item collection item password &rest attributes
 This function creates a new item in @var{collection} with label
address@hidden and password @var{PASSWORD}.  @var{attributes} are
address@hidden 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:
 
@@ -347,7 +347,7 @@
 @end defun
 
 @defun secrets-search-items collection &rest attributes
-Searchs items in @var{collection} with @var{attributes}.
+Search items in @var{collection} with @var{attributes}.
 @var{attributes} are key-value pairs, as used in
 @code{secrets-create-item}.  Example:
 
@@ -370,14 +370,14 @@
 
 The auth-source library only has a few functions for external use.
 
address@hidden auth-source-search SPEC
-
-TODO: how to include docstring?
-
address@hidden auth-source-search &rest spec &key type max host user port 
secret require create delete &allow-other-keys
+This function searches (or modifies) authentication backends according
+to @var{spec}.  See the function's doc-string for details.
address@hidden TODO more details.
 @end defun
 
 Let's take a look at an example of using @code{auth-source-search}
-from Gnus' @code{nnimap.el}.
+from Gnus's @code{nnimap.el}.
 
 @example
 (defun nnimap-credentials (address ports)
@@ -432,22 +432,21 @@
 So the responsibility of the API user that specified @code{:create t}
 is to call the @code{:save-function} if it's provided.
 
address@hidden auth-source-delete SPEC
-
-TODO: how to include docstring?
-
address@hidden defun
-
address@hidden auth-source-forget SPEC
-
-TODO: how to include docstring?
-
address@hidden defun
-
address@hidden auth-source-forget+ SPEC
-
-TODO: how to include docstring?
-
address@hidden auth-source-delete &rest spec &key delete &allow-other-keys
+This function deletes entries matching @var{spec} from the
+authentication backends.  It returns the entries that were deleted.
+The backend may not actually delete the entries.
address@hidden defun
+
address@hidden auth-source-forget spec
+This function forgets any cached data that exactly matches @var{spec}.
+It returns @code{t} if it forget some data, and @code{nil} if no
+matching data was found.
address@hidden defun
+
address@hidden auth-source-forget+ &rest spec &allow-other-keys
+This function forgets any cached data matching @var{spec}.
+It returns the number of items forgotten.
 @end defun
 
 @node GnuPG and EasyPG Assistant Configuration