Improve platform-indepdendent credential docs.

Add material around attributes.

Author: brotskydotcom

src/credential.rs

@@ -1,6 +1,6 @@
 /*!
 
-# Platorm-independent secure storage model
+# Platform-independent secure storage model
 
 This module defines a plug and play model for platform-specific credential stores.
 The model comprises two traits: [CredentialBuilderApi] for the underlying store
@@ -44,17 +44,25 @@ pub trait CredentialApi {
  /// This will persist the secret in the underlying store.
  fn set_secret(&self, password: &[u8]) -> Result<()>;
 
- /// Retrieve a password (a string) from the credential, if one has been set.
+ /// Retrieve the password (a string) from the underlying credential.
  ///
- /// This has no effect on the underlying store.
+ /// This has no effect on the underlying store. If there is no credential
+ /// for this entry, a [NoEntry](crate::Error::NoEntry) error is returned.
  fn get_password(&self) -> Result<String>;
 
- /// Retrieve a secret (a byte array) from the credential, if one has been set.
+ /// Retrieve a secret (a byte array) from the credential.
  ///
- /// This has no effect on the underlying store.
+ /// This has no effect on the underlying store. If there is no credential
+ /// for this entry, a [NoEntry](crate::Error::NoEntry) error is returned.
  fn get_secret(&self) -> Result<Vec<u8>>;
 
- /// Get the attributes on this credential from the underlying store.
+ /// Get the secure store attributes on this entry's credential.
+ ///
+ /// Each credential store may support reading and updating different
+ /// named attributes; see the documentation on each of the stores
+ /// for details. Note that the keyring itself uses some of these
+ /// attributes to map entries to their underlying credential; these
+ /// _controlled_ attributes are not available for reading or updating.
  ///
  /// We provide a default (no-op) implementation of this method
  /// for backward compatibility with stores that don't implement it.
@@ -65,7 +73,14 @@ pub trait CredentialApi {
  Ok(HashMap::new())
  }
 
- /// Update attributes on the underlying credential store.
+ /// Update the secure store attributes on this entry's credential.
+ ///
+ /// Each credential store may support reading and updating different
+ /// named attributes; see the documentation on each of the stores
+ /// for details. The implementation will ignore any attribute names
+ /// that you supply that are not available for update. Because the
+ /// names used by the different stores tend to be distinct, you can
+ /// write cross-platform code that will work correctly on each platform.
  ///
  /// We provide a default no-op implementation of this method
  /// for backward compatibility with stores that don't implement it.