sc-keystore: Improve docs (#3334)

Close: https://github.com/paritytech/polkadot-sdk/issues/3320

@Hugo-Trentesaux are these docs better for explaining the internals?

substrate/client/keystore/src/local.rs

@@ -47,6 +47,13 @@ pub struct LocalKeystore(RwLock<KeystoreInner>);
 
 impl LocalKeystore {
 	/// Create a local keystore from filesystem.
+	///
+	/// The keystore will be created at `path`. The keystore optionally supports to encrypt/decrypt
+	/// the keys in the keystore using `password`.
+	///
+	/// NOTE: Even when passing a `password`, the keys on disk appear to look like normal secret
+	/// uris. However, without having the correct password the secret uri will not generate the
+	/// correct private key. See [`SecretUri`](sp_core::crypto::SecretUri) for more information.
 	pub fn open<T: Into<PathBuf>>(path: T, password: Option<SecretString>) -> Result<Self> {
 		let inner = KeystoreInner::open(path, password)?;
 		Ok(Self(RwLock::new(inner)))

substrate/primitives/core/src/crypto.rs

@@ -773,6 +773,8 @@ mod dummy {
 /// Similarly an empty password (ending the `SURI` with `///`) is perfectly valid and will
 /// generally be equivalent to no password at all.
 ///
+/// The `password` is used as salt when generating the seed from the BIP-39 key phrase.
+///
 /// # Example
 ///
 /// Parse [`DEV_PHRASE`] secret uri with junction: