Update docs to explain that the :save-function will only run the first time.

* auth.texi (Help for developers): Update docs to explain that the
:save-function will only run the first time.

diff --git a/texi/ChangeLog b/texi/ChangeLog
index 76bc116..2c41fd2 100644 (file)
--- a/texi/ChangeLog
+++ b/texi/ChangeLog
@@ -1,3 +1,8 @@
+2011-03-12  Teodor Zlatanov  <tzz@lifelogs.com>
+
+       * auth.texi (Help for developers): Update docs to explain that the
+       :save-function will only run the first time.
+
 2011-03-08  Teodor Zlatanov  <tzz@lifelogs.com>
 
        * auth.texi (Help for developers): Show example of using

diff --git a/texi/auth.texi b/texi/auth.texi
index 2f2c9cc..fbcbe8c 100644 (file)
--- a/texi/auth.texi
+++ b/texi/auth.texi
@@ -289,11 +289,21 @@ Later, after a successful login, @code{nnimal.el} calls the
    (funcall (nth 2 credentials)))
 @end example
 
-Which will work whether the @code{:save-function} was provided or not.
+This will work whether the @code{:save-function} was provided or not.
 @code{:save-function} will be provided only when a new entry was
 created, so this effectively says ``after a successful login, save the
 authentication information we just used, if it was newly created.''
 
+After the first time it's called, the @code{:save-function} will not
+run again (but it will log something if you have set
+@code{auth-source-debug} to @code{'trivia}).  This is so it won't ask
+the same question again, which is annoying.  This is so it won't ask
+the same question again, which is annoying.  This is so it won't ask
+the same question again, which is annoying.
+
+So the responsibility of the API user that specified @code{:create t}
+is to call the @code{:save-function} if it's provided.
+
 @defun auth-source-delete SPEC
 
 TODO: how to include docstring?