Add a comment on scalarmult usage

src/libsodium/include/sodium/crypto_scalarmult.h

@@ -25,6 +25,14 @@ const char *crypto_scalarmult_primitive(void);
 SODIUM_EXPORT
 int crypto_scalarmult_base(unsigned char *q, const unsigned char *n);
 
+/*
+ * NOTE: Do not use the result of this function directly.
+ *
+ * Hash the result with the public keys in order to compute a shared
+ * secret key: H(q || client_pk || server_pk)
+ *
+ * Or unless this is not an option, use the crypto_kx() API instead.
+ */
 SODIUM_EXPORT
 int crypto_scalarmult(unsigned char *q, const unsigned char *n,
                       const unsigned char *p)

src/libsodium/include/sodium/crypto_scalarmult_curve25519.h

@@ -17,6 +17,14 @@ size_t crypto_scalarmult_curve25519_bytes(void);
 SODIUM_EXPORT
 size_t crypto_scalarmult_curve25519_scalarbytes(void);
 
+/*
+ * NOTE: Do not use the result of this function directly.
+ *
+ * Hash the result with the public keys in order to compute a shared
+ * secret key: H(q || client_pk || server_pk)
+ *
+ * Or unless this is not an option, use the crypto_kx() API instead.
+ */
 SODIUM_EXPORT
 int crypto_scalarmult_curve25519(unsigned char *q, const unsigned char *n,
                                  const unsigned char *p)

src/libsodium/include/sodium/crypto_scalarmult_ed25519.h

@@ -18,6 +18,14 @@ size_t crypto_scalarmult_ed25519_bytes(void);
 SODIUM_EXPORT
 size_t crypto_scalarmult_ed25519_scalarbytes(void);
 
+/*
+ * NOTE: Do not use the result of this function directly.
+ *
+ * Hash the result with the public keys in order to compute a shared
+ * secret key: H(q || client_pk || server_pk)
+ *
+ * Or unless this is not an option, use the crypto_kx() API instead.
+ */
 SODIUM_EXPORT
 int crypto_scalarmult_ed25519(unsigned char *q, const unsigned char *n,
                               const unsigned char *p)