Merge pull request #198 from brotskydotcom/issue-197

Make the default module alias public.

Cargo.toml

@@ -6,7 +6,7 @@ keywords = ["password", "credential", "keychain", "keyring", "cross-platform"]
 license = "MIT OR Apache-2.0"
 name = "keyring"
 repository = "https://github.com/hwchen/keyring-rs.git"
-version = "3.0.3"
+version = "3.0.4"
 rust-version = "1.75"
 edition = "2021"
 exclude = [".github/"]

src/credential.rs

@@ -6,7 +6,26 @@ This module defines a plug and play model for platform-specific credential store
 The model comprises two traits: [CredentialBuilderApi] for the underlying store
 and [CredentialApi] for the entries in the store.  These traits must be implemented
 in a thread-safe way, a requirement captured in the [CredentialBuilder] and
-[CredentialApi] types that wrap them.
+[Credential] types that wrap them.
+
+Note that you must have an instance of a credential builder in
+your hands in order to call the [CredentialBuilder] API.  Because each credential
+builder implementation lives in a platform-specific module, the cross-platform way to
+get your hands on the one currently being used to create entries is to ask
+for the builder from the `default` module alias.  For example, to
+determine whether the credential builder currently being used
+persists its credentials across machine reboots, you might use a snippet like this:
+
+```rust
+use keyring::{default, credential};
+
+let persistence = default::default_credential_builder().persistence();
+if  matches!(persistence, credential::CredentialPersistence::UntilDelete) {
+    println!("The default credential builder persists credentials on disk!")
+} else {
+    println!("The default credential builder doesn't persist credentials on disk!")
+}
+```
  */
 use super::Result;
 use std::any::Any;

src/lib.rs

@@ -148,8 +148,8 @@ then retrieving that as a password will return a
 [BadEncoding](Error::BadEncoding) error.
 The returned error will have the raw bytes attached,
 so you can access them, but you can also just fetch
-them directly using [Entry::get_secret] rather than
-[Entry:get_password].
+them directly using [get_secret](Entry::get_password) rather than
+[get_password](Entry::get_secret).
 
 While this crate's code is thread-safe, the underlying credential
 stores may not handle access from different threads reliably.
@@ -182,7 +182,7 @@ compile_error!("You can enable at most one keystore per target architecture");
 #[cfg(all(target_os = "linux", feature = "linux-native"))]
 pub mod keyutils;
 #[cfg(all(target_os = "linux", feature = "linux-native"))]
-use keyutils as default;
+pub use keyutils as default;
 
 #[cfg(all(
     any(target_os = "linux", target_os = "freebsd", target_os = "openbsd"),
@@ -193,7 +193,7 @@ pub mod secret_service;
     any(target_os = "linux", target_os = "freebsd", target_os = "openbsd"),
     any(feature = "sync-secret-service", feature = "async-secret-service")
 ))]
-use secret_service as default;
+pub use secret_service as default;
 
 #[cfg(all(
     target_os = "linux",
@@ -203,29 +203,29 @@ use secret_service as default;
         feature = "async-secret-service"
     ))
 ))]
-use mock as default;
+pub use mock as default;
 #[cfg(all(
     any(target_os = "freebsd", target_os = "openbsd"),
     not(any(feature = "sync-secret-service", feature = "async-secret-service"))
 ))]
-use mock as default;
+pub use mock as default;
 
 //
 // pick the Apple keystore
 //
 #[cfg(all(target_os = "macos", feature = "apple-native"))]
 pub mod macos;
 #[cfg(all(target_os = "macos", feature = "apple-native"))]
-use macos as default;
+pub use macos as default;
 #[cfg(all(target_os = "macos", not(feature = "apple-native")))]
-use mock as default;
+pub use mock as default;
 
 #[cfg(all(target_os = "ios", feature = "apple-native"))]
 pub mod ios;
 #[cfg(all(target_os = "ios", feature = "apple-native"))]
-use ios as default;
+pub use ios as default;
 #[cfg(all(target_os = "ios", not(feature = "apple-native")))]
-use mock as default;
+pub use mock as default;
 
 //
 // pick the Windows keystore
@@ -234,9 +234,9 @@ use mock as default;
 #[cfg(all(target_os = "windows", feature = "windows-native"))]
 pub mod windows;
 #[cfg(all(target_os = "windows", not(feature = "windows-native")))]
-use mock as default;
+pub use mock as default;
 #[cfg(all(target_os = "windows", feature = "windows-native"))]
-use windows as default;
+pub use windows as default;
 
 #[cfg(not(any(
     target_os = "linux",
@@ -246,7 +246,7 @@ use windows as default;
     target_os = "ios",
     target_os = "windows",
 )))]
-use mock as default;
+pub use mock as default;
 
 pub mod credential;
 pub mod error;