From 9e23f48d702ef6f731e2bb2af50c3955d3d170a4 Mon Sep 17 00:00:00 2001
From: "B. Petersen" <r10s@b44t.com>
Date: Fri, 16 Nov 2018 15:53:10 +0100
Subject: [PATCH] refine dc_configure() doc

---
 src/dc_configure.c | 47 ++++++++++++++++++++++++++++++----------------
 1 file changed, 31 insertions(+), 16 deletions(-)

diff --git a/src/dc_configure.c b/src/dc_configure.c
index 5a3139bd..88a0fd2a 100644
--- a/src/dc_configure.c
+++ b/src/dc_configure.c
@@ -722,34 +722,49 @@ cleanup:
 
 
 /**
- * Configure and connect a context.
- * For this, the function creates a job that is executed in the IMAP-thread then;
+ * Configure a context.
+ * For this purpose, the function creates a job
+ * that is executed in the IMAP-thread then;
  * this requires to call dc_perform_imap_jobs() regularly.
  *
- * - Before you call this function, you should set at least `addr` and `mail_pw`
- *   using dc_set_config().
+ * - Before you call this function,
+ *   you must set at least `addr` and `mail_pw` using dc_set_config().
  *
- * - Use `mail_user` to use a different user name than `addr` and `send_pw` to
- *   use a different password for the SMTP server (otherwise `mail_pw` is used)
+ * - Use `mail_user` to use a different user name than `addr`
+ *   and `send_pw` to use a different password for the SMTP server.
  *
- *     - If _no_ more options are specified, the function tries to get these
- *       **using autoconfigure/autodiscover**.
+ *     - If _no_ more options are specified,
+ *       the function **uses autoconfigure/autodiscover**
+ *       to get the full configuration from well-known URLs.
  *
- *     - If _more_ options as `mail_server`, `mail_port`, `send_server`, `send_port`, `send_user` or `server_flags`
- *       are specified, **autoconfigure/autodiscover is skipped**.
+ *     - If _more_ options as `mail_server`, `mail_port`, `send_server`,
+ *       `send_port`, `send_user` or `server_flags` are specified,
+ *       **autoconfigure/autodiscover is skipped**.
  *
- * - While dc_configure() returns immediately, the started configuration-job may take a while,
- *   you can stop it using dc_stop_ongoing_process().
+ * While dc_configure() returns immediately,
+ * the started configuration-job may take a while.
+ * You can stop it using dc_stop_ongoing_process().
  *
- * - The function sends out a number of #DC_EVENT_CONFIGURE_PROGRESS events that may be used to create
- *   a progress bar or stuff like that.
+ * During configuration, #DC_EVENT_CONFIGURE_PROGRESS events are emmited;
+ * they may be used to create a progress bar.
+ *
+ * On a successfull configuration,
+ * the core makes a copy of the parameters mentioned above:
+ * the original parameters as are never modified by the core.
+ *
+ * UI-implementors should keep this in mind -
+ * eg. if the UI wants to prefill a configure-edit-dialog with these parameters,
+ * the UI should reset them if the user cancels the dialog
+ * after a configure-attempts has failed.
+ * Otherwise the parameters may not reflect the current configuation.
  *
  * @memberof dc_context_t
  * @param context The context object as created by dc_context_new().
  * @return None.
  *
- * There is no need to call this every program start, the result is saved in the
- * database and you can use the connection directly:
+ * There is no need to call dc_configure() every program start,
+ * the configuration result is saved in the database
+ * and you can use the connection directly:
  *
  * ~~~
  * if (!dc_is_configured(context)) {