Merge pull request #114 from brotskydotcom/doc-updates

Revamp the docs for v2. Also tweaked visibility of a few classes for documentation purposes.

This brings us to 2.0.0-rc.3, and will likely be promoted to our 2.0 release.

Author: brotskydotcom

Cargo.toml

@@ -6,9 +6,10 @@ keywords = ["password", "credential", "keychain", "keyring", "cross-platform"]
 license = "MIT OR Apache-2.0"
 name = "keyring"
 repository = "https://github.com/hwchen/keyring-rs.git"
-version = "2.0.0-rc.2"
+version = "2.0.0-rc.3"
 edition = "2021"
 exclude = [".github/"]
+readme = "README.md"
 
 [features]
 default = ["linux-secret-service"]

README.md

@@ -3,78 +3,94 @@
 [![Crates.io](https://img.shields.io/crates/v/keyring.svg?style=flat-square)](https://crates.io/crates/keyring)
 [![API Documentation on docs.rs](https://docs.rs/keyring/badge.svg)](https://docs.rs/keyring)
 
-A cross-platform library to manage storage and retrieval of passwords (and other credential-like secrets) in the underlying platform secure store, with a fully-developed example that provides a command-line interface.
-
-Published on [crates.io](https://crates.io/crates/keyring)
+A cross-platform library to manage storage and retrieval of passwords
+(and other secrets) in the underlying platform secure store, 
+with a fully-developed example that provides a command-line interface.
 
 ## Usage
 
-__Currently supports Linux, iOS, macOS, and Windows.__ Please file issues if you have any problems or bugs!
+**Currently supports Linux, iOS, macOS, and Windows.**
+Please file issues if you have have questions or problems.
 
 To use this library in your project add the following to your `Cargo.toml` file:
 
 ```toml
 [dependencies]
-keyring = "1"
+keyring = "2"
 ```
 
-This will give you access to the `keyring` crate in your code. Now you can use  the `Entry::new` function to create a new keyring entry. The `new` function expects a non-empty `service` name and a non-empty `username` which together identify the entry.
+This will give you access to the `keyring` crate in your code.
+Now you can use  the `Entry::new` function to create a new keyring entry.
+The `new` function takes a service name 
+and a user name which together identify the entry.
 
-Passwords can be added to an entry using its `set_password` method.  They can then be read back using the `get_password` method, and deleted using the `delete_password` method.  (The persistence of the `Entry` is determined via Rust rules, so deleting the password doesn't delete the entry, but it does delete the underlying platform credential which was used to store the password.)
+Passwords can be added to an entry using its `set_password` method.
+They can then be read back using the `get_password` method, 
+and removed using the `delete_password` method.  
+(The persistence of the `Entry` is determined via Rust rules, 
+so deleting the password doesn't delete the entry, 
+but it does delete the underlying platform credential 
+which is used to store the password.)
 
 ```rust
-extern crate keyring;
-
-use std::error::Error;
-
-fn main() -> Result<(), Box<dyn Error>> {
-    let service = "my_application";
-    let username = "my_name";
-    let entry = keyring::Entry::new(&service, &username);
-
-    let password = "topS3cr3tP4$$w0rd";
-    entry.set_password(&password)?;
+use keyring::{Entry, Result};
 
+fn main() -> Result<()> {
+    let entry = Entry::new("my_service", "my_name");
+    entry.set_password("topS3cr3tP4$$w0rd")?;
     let password = entry.get_password()?;
     println!("My password is '{}'", password);
-
     entry.delete_password()?;
-    println!("My password has been deleted");
-
     Ok(())
 }
 ```
 
 ## Errors
 
-Creating and operating on entries can yield a `keyring::Error` which provides both a platform-independent code that classifies the error and, where available, underlying platform errors and/or more information about what went wrong.
+Creating and operating on entries can yield a `keyring::Error` 
+which provides both a platform-independent code 
+that classifies the error and, where relevant, 
+underlying platform errors or more information about what went wrong.
 
 ## Examples
 
-The keychain-rs project contains a sample application (`cli`) and a sample library (`ios`).
-
-The application is a command-line interface to the keyring.  This can be a great way to explore how the library is used, and it allows experimentation with the use of different service names, usernames, and targets.  When run in "singly verbose" mode (-v), it outputs the retrieved credentials on each `get` run.  When run in "doubly verbose" mode (-vv), it also outputs any errors returned.  This can be a great way to see which errors result from which conditions on each platform.
-
-The sample library is a full exercise of all the iOS functionality; it's meant to be loaded into an iOS test harness such as the one found in [this project](https://github.com/brotskydotcom/rust-on-ios). While the library can be compiled and linked to on macOS as well, doing so doesn't provide any advantages over the standard macOS tests.
+The keychain-rs project contains a sample application (`cli`) 
+and a sample library (`ios`).
+
+The application is a command-line interface to the keyring.  
+It can be used to explore how the library is used.
+It can also be used in debugging keyring-based applications
+to probe the contents of the credential store.
+When run in "singly verbose" mode (-v),
+it outputs the retrieved credentials on each `get` run.
+When run in "doubly verbose" mode (-vv),
+it also outputs any errors returned.
+
+The sample library is a full exercise of all the iOS functionality; 
+it's meant to be loaded into an iOS test harness 
+such as the one found in 
+[this project](https://github.com/brotskydotcom/rust-on-ios).
+While the library can be compiled and linked to on macOS as well,
+doing so doesn't provide any advantages over the standard macOS tests.
 
 ## Client Testing
 
-This crate comes with a "mock" credential store that can be used by clients who want to test without accessing the native platform store.  The mock store is cross-platform and allows mocking errors as well as successes.
+This crate comes with a "mock" credential store
+that can be used by clients who want to test 
+without accessing the native platform store.
+The mock store is cross-platform 
+and allows mocking errors as well as successes.
 
 ## Extensibility
 
-This crate comes with built-in support for the keychain on Mac, the credential manager on Windows, and both secret-service and the kernel keyring on Linux.  But it's also designed to allow clients to "bring their own credential stores" by providing traits that clients can implement.  See the [developer docs](https://docs.rs/keyring/latest/keyring/) for details.
-
-## Dev Notes
-
-* We build using GitHub CI.
-* Each tag is built on Ubuntu x64, Win 10 x64, and Mac intel x64.  The `cli` example executable is posted for all platforms with the tag.
-
-### Headless Linux
-
-If you are trying to use keyring on a headless linux box, be aware that there are known issues with getting dbus and secret-service and the gnome keyring to work properly in headless environments.  For a quick workaround, look at how this project's [CI workflow](https://github.com/hwchen/keyring-rs/blob/master/.github/workflows/build.yaml) uses the [linux-test.sh](https://github.com/hwchen/keyring-rs/blob/master/linux-test.sh) script; a similar solution is also documented in the [Python Keyring docs](https://pypi.org/project/keyring/) (search for "Using Keyring on headless Linux systems").  For an excellent treatment of all the headless dbus issues, see [this answer on ServerFault](https://serverfault.com/a/906224/79617).
-
-Note that you can build this crate without secret-service support; this makes the Linux keyring (which works normally on headless linux) the default credential store on Linux platforms.
+This crate comes with built-in support for the keychain on Mac,
+the credential manager on Windows, 
+and both secret-service and the kernel keyutils on Linux.
+But it's also designed to allow clients 
+to "bring their own credential stores" 
+by providing traits that clients can implement.
+See the [developer docs](https://docs.rs/keyring/latest/keyring/) 
+for details.
 
 ## License
 
@@ -87,7 +103,8 @@ at your option.
 
 ## Contributors
 
-Thanks to the following for helping make this library better, whether through contributing code, discussion, or bug reports!
+Thanks to the following for helping make this library better, 
+whether through contributing code, discussion, or bug reports!
 
 - @Alexei-Barnes
 - @bhkaminski
@@ -111,8 +128,14 @@ Thanks to the following for helping make this library better, whether through co
 - @steveatinfincia
 - @Sytten
 
-If you should be on this list, but don't find yourself, please contact @brotskydotcom.
+If you should be on this list, but don't find yourself, 
+please contact @brotskydotcom.
 
 ### Contribution
 
-Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+Unless you explicitly state otherwise, 
+any contribution intentionally submitted 
+for inclusion in the work by you, 
+as defined in the Apache-2.0 license, 
+shall be dual licensed as above, 
+without any additional terms or conditions.

build-xplat-docs.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+cargo doc --no-deps --target x86_64-unknown-linux-musl $OPEN_DOCS
+cargo doc --no-deps --target x86_64-pc-windows-gnu $OPEN_DOCS
+cargo doc --no-deps --target aarch64-apple-darwin $OPEN_DOCS
+cargo doc --no-deps --target aarch64-apple-ios $OPEN_DOCS

src/credential.rs

@@ -1,22 +1,38 @@
 /*!
+
+# Platorm-independent secure storage model
+
 This module defines a plug and play model for platform-specific credential stores.
-The model comprises two traits: `CredentialBuilder` for the store service
-and `Credential` for the credentials produced by the service.
+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.
  */
 use super::Result;
 use std::any::Any;
 
-/// This trait defines the API that all credentials must implement.
+/// The API that [credentials](Credential) implement.
 pub trait CredentialApi {
-    /// Set a password in the underlying store
+    /// Set the credential's password.
+    ///
+    /// This will persist the password in the underlying store.
     fn set_password(&self, password: &str) -> Result<()>;
-    /// Retrieve a password from the underlying store
+    /// Retrieve a password from the credential, if one has been set.
+    ///
+    /// This has no effect on the underlying store.
     fn get_password(&self) -> Result<String>;
-    /// Delete a password from the underlying store
+    /// Forget the credential's password, if one has been set.
+    ///
+    /// This will also remove the credential from the underlying store,
+    /// so a second call to delete_password will return
+    /// a [NoEntry](crate::Error::NoEntry) error.
     fn delete_password(&self) -> Result<()>;
-    /// Cast the credential object to Any.  This allows clients
+    /// Return the underlying concrete object cast to [Any](std::any::Any).
+    ///
+    /// This allows clients
     /// to downcast the credential to its concrete type so they
-    /// can do platform-specific things with it (e.g, unlock it)
+    /// can do platform-specific things with it (e.g.,
+    /// query its attributes in the underlying store).
     fn as_any(&self) -> &dyn Any;
 }
 
@@ -26,16 +42,21 @@ impl std::fmt::Debug for Credential {
     }
 }
 
-/// Credentials must be usable from multiple threads, and they must
-/// be movable from thread to thread, so they must be Send and Sync.
+/// A thread-safe implementation of the [Credential API](CredentialApi).
 pub type Credential = dyn CredentialApi + Send + Sync;
 
-/// This trait defines the API that Credential Builders must implement.
+/// The API that [credential builders](CredentialBuilder) implement.
 pub trait CredentialBuilderApi {
-    /// Build a platform credential for the given parameters
+    /// Create a credential identified by the given target, service, and user.
+    ///
+    /// This typically has no effect on the content of the underlying store.
+    /// A credential need not be persisted until its password is set.
     fn build(&self, target: Option<&str>, service: &str, user: &str) -> Result<Box<Credential>>;
-    /// Cast the builder as type Any.  This is not so much for clients.
-    /// as it is to allow us to derive a Debug trait for builders.
+    /// Return the underlying concrete object cast to [Any](std::any::Any).
+    ///
+    /// Because credential builders need not have any internal structure,
+    /// this call is not so much for clients
+    /// as it is to allow automatic derivation of a Debug trait for builders.
     fn as_any(&self) -> &dyn Any;
 }
 
@@ -45,8 +66,5 @@ impl std::fmt::Debug for CredentialBuilder {
     }
 }
 
-/// Credential Builders must be Sync so they can be invoked from
-/// multiple threads simultaneously.  Although no one expects a
-/// Credential Builder to be passed from one thread to another,
-/// they are usually objects, so Send should be easy.
+/// A thread-safe implementation of the [CredentialBuilder API](CredentialBuilderApi).
 pub type CredentialBuilder = dyn CredentialBuilderApi + Send + Sync;