fixup! fixup! net/sock/dtls: add documentation on multi-credential

leandrolanzieri · leandrolanzieri · commit 74ea5086deba · 2021-03-19T08:37:23.000+01:00
diff --git a/sys/include/net/sock/dtls.h b/sys/include/net/sock/dtls.h
@@ -481,19 +481,21 @@
  *
  * ### Multi-credential handling
  *
- * Each sock needs at least one credential tag. Extra credentials can be added
- * and removed using @ref sock_dtls_add_credential and @ref sock_dtls_remove_credential
- * respectively (found in `net/sock/dtls/creds.h`).
+ * Each sock needs at least one credential tag to operate. `sock_dtls_create` allows to optionally
+ * assign an initial credential. Extra credentials can be added and removed using
+ * @ref sock_dtls_add_credential and @ref sock_dtls_remove_credential respectively (found in
+ * `net/sock/dtls/creds.h`).
  *
  * #### Pre-shared Keys Cipher Suites
- * In the case of PSK, a server can optionally indicate a hint to help the server to decide which
+ * In the case of PSK, a server can optionally indicate a hint to help the client to decide which
  * PSK Identity to use, using @ref sock_dtls_set_psk_identity_hint. The client application can
  * decide which credential to use based on the sent hint and/or the session information, by
- * registering a callback with @ref sock_dtls_set_client_psk_cb. If no callback is registered the
- * credential is chosen as follows: if a hint is sent by the server, all credentials registered to
- * the sock are checked for a matching @ref psk_params_t::hint "hint". A credential is select on
- * matching hint. If no credential matches the hint or no hint is provided, the first PSK credential
- * registered in the sock is used.
+ * registering a callback with @ref sock_dtls_set_client_psk_cb. If no callback is registered, or
+ * fails to chose a tag (i.g. it returns @ref CREDMAN_TAG_EMPTY), the credential is chosen as
+ * follows: if a hint is sent by the server, all credentials registered to the sock are checked for
+ * a matching @ref psk_params_t::hint "hint". A credential is selected on matching hint. If no
+ * credential matches the hint or no hint is provided, the first PSK credential registered in the
+ * sock is used.
  *
  * #### Elliptic Curve Cryptography Cipher Suites
  * When using ECC both client and server applications can register a callback to decide which of
