From 38531362b56a7af0e2288dd785a3d8fa8f574779 Mon Sep 17 00:00:00 2001
From: Daniel Brotsky <dan@brotsky.com>
Date: Tue, 23 Jul 2024 15:06:27 -0700
Subject: [PATCH] Make the `default` module alias public.

Also add a doc example for how to get your hands on the default credential builder.

This fixes hwchen/keyring-rs#197.
---
 src/credential.rs | 21 ++++++++++++++++++++-
 src/lib.rs        | 26 +++++++++++++-------------
 2 files changed, 33 insertions(+), 14 deletions(-)

diff --git a/src/credential.rs b/src/credential.rs
index 5404012..fbdf91c 100644
--- a/src/credential.rs
+++ b/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;
diff --git a/src/lib.rs b/src/lib.rs
index 974e879..0bb7db4 100644
--- a/src/lib.rs
+++ b/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,12 +203,12 @@ 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
@@ -216,16 +216,16 @@ use mock as default;
 #[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;