From f83e26f21375c3d7c53df56569f4d183f58cf11a Mon Sep 17 00:00:00 2001
From: Heiko Schaefer <heiko@schaefer.name>
Date: Fri, 13 May 2022 19:14:41 +0200
Subject: [PATCH] Minor additions to documentation

---
 openpgp-card/src/card_do.rs | 10 +++++++++-
 openpgp-card/src/lib.rs     | 26 ++++++++++++++++++--------
 2 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/openpgp-card/src/card_do.rs b/openpgp-card/src/card_do.rs
index 7813aaa..f37aae3 100644
--- a/openpgp-card/src/card_do.rs
+++ b/openpgp-card/src/card_do.rs
@@ -309,7 +309,8 @@ impl Display for UIF {
     }
 }
 
-/// User interaction setting.
+/// User interaction setting: is a 'touch' needed to perform an operation on the card?
+/// This setting is used in 4.4.3.6 User Interaction Flag (UIF)
 ///
 /// See spec pg 24 and <https://github.com/Yubico/yubikey-manager/blob/main/ykman/openpgp.py>
 #[non_exhaustive]
@@ -403,6 +404,7 @@ impl Display for Features {
     }
 }
 
+/// 4.4.3.8 Key Information
 pub struct KeyInformation(Vec<u8>);
 
 impl From<Vec<u8>> for KeyInformation {
@@ -488,6 +490,8 @@ impl Display for KeyInformation {
     }
 }
 
+/// KeyStatus is contained in `KeyInformation`. It encodes if key material on a card was imported
+/// or generated on the card.
 #[non_exhaustive]
 pub enum KeyStatus {
     NotPresent,
@@ -759,6 +763,7 @@ impl Display for CardholderRelatedData {
 }
 
 /// 4.4.3.5 Sex
+///
 /// Encoded in accordance with <https://en.wikipedia.org/wiki/ISO/IEC_5218>
 #[derive(Debug, PartialEq, Clone, Copy)]
 pub enum Sex {
@@ -805,6 +810,9 @@ impl From<u8> for Sex {
     }
 }
 
+/// Individual language for Language Preferences (4.4.3.4), accessible via `CardholderRelatedData`.
+///
+/// Encoded according to <https://en.wikipedia.org/wiki/ISO_639-1>
 #[derive(Debug, PartialEq, Clone, Copy)]
 pub enum Lang {
     Value([u8; 2]),
diff --git a/openpgp-card/src/lib.rs b/openpgp-card/src/lib.rs
index 545c834..691a986 100644
--- a/openpgp-card/src/lib.rs
+++ b/openpgp-card/src/lib.rs
@@ -13,17 +13,18 @@
 //! [OpenPGP implementation](https://www.openpgp.org/software/developer/).
 //!
 //! This library can't directly access cards by itself. Instead, users
-//! need to supply an implementation of the [`CardBackend`]
-//! / [`CardTransaction`] traits, to access cards.
-//!
-//! The companion crate
+//! need to supply a backend that implements the [`CardBackend`]
+//! / [`CardTransaction`] traits. The companion crate
 //! [openpgp-card-pcsc](https://crates.io/crates/openpgp-card-pcsc)
-//! offers a backend that uses [pcsclite](https://pcsclite.apdu.fr/) to
-//! communicate with smartcards.
+//! offers a backend that uses [PC/SC](https://en.wikipedia.org/wiki/PC/SC) to
+//! communicate with Smart Cards.
 //!
 //! The [openpgp-card-sequoia](https://crates.io/crates/openpgp-card-sequoia)
-//! crate offers a higher level wrapper based on the
-//! [Sequoia PGP](https://sequoia-pgp.org/) implementation.
+//! crate offers a higher level wrapper based on the [Sequoia PGP](https://sequoia-pgp.org/)
+//! implementation.
+//!
+//! See the [architecture diagram](https://gitlab.com/hkos/openpgp-card#architecture) for
+//! a visualization.
 
 extern crate core;
 
@@ -498,10 +499,19 @@ impl From<ShortTag> for Vec<u8> {
     }
 }
 
+/// Specify a PIN to *verify* (distinguishes between `Sign`, `User` and `Admin`).
+///
+/// (Note that for PIN *management*, in particular changing a PIN, "signing and user" are
+/// not distinguished. They always share the same PIN value `PW1`)
 #[derive(Debug, Clone, Copy, Eq, PartialEq)]
 pub enum PinType {
+    /// Verify PW1 in mode P2=81 (for the PSO:CDS operation)
     Sign,
+
+    /// Verify PW1 in mode P2=82 (for all other User operations)
     User,
+
+    /// Verify PW3 (for Admin operations)
     Admin,
 }