Doc fix

Add missing doc strings, and fix bare URLs in existing docs.

Signed-off-by: setrofim <setrofim@gmail.com>

Author: setrofim

src/base64.rs

@@ -15,6 +15,7 @@ pub fn decode_str(v: &str) -> Result<Vec<u8>, Error> {
         .map_err(|e| Error::ParseError(e.to_string()))
 }
 
+/// a `Vec<u8>` encoded as base64 in human readable serialization
 #[derive(Debug, PartialEq)]
 pub struct Bytes(Vec<u8>);
 

src/ear.rs

@@ -33,13 +33,13 @@ enum KeyFormat {
 pub struct Ear {
     /// The EAT profile of the associated claim-set
     ///
-    /// See https://datatracker.ietf.org/doc/html/draft-ietf-rats-eat-19#name-eat_profile-eat-profile-cla
+    /// See <https://datatracker.ietf.org/doc/html/draft-ietf-rats-eat-19#name-eat_profile-eat-profile-cla>
     pub profile: String,
     /// "Issued At" -- the time at which the EAR is issued
     ///
     /// See:
-    /// - https://datatracker.ietf.org/doc/html/draft-ietf-rats-eat-19#section-4.3.1
-    /// - https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6
+    /// - <https://datatracker.ietf.org/doc/html/draft-ietf-rats-eat-19#section-4.3.1>
+    /// - <https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6>
     pub iat: i64,
     /// Identifier of the verifier that created the EAR
     pub vid: VerifierID,

src/error.rs

@@ -2,24 +2,34 @@
 
 use thiserror::Error;
 
+/// EAR errors
 #[derive(Error, Debug)]
 pub enum Error {
+    /// an error occured while parsing serialized structures
     #[error("parse error: {0}")]
     ParseError(String),
+    /// an error occured while formatting structures
     #[error("format error: {0}")]
     FormatError(String),
+    /// an error occured during signing
     #[error("sign error: {0}")]
     SignError(String),
+    /// an error occured during verification
     #[error("verify error: {0}")]
     VerifyError(String),
+    /// an error occured while processing cryptographic keys
     #[error("key error: {0}")]
     KeyError(String),
+    /// an error occured during validation of the internal integrity of structures
     #[error("validation error: {0}")]
     ValidationError(String),
+    // invalid claim value
     #[error("invalid value: {0}")]
     InvalidValue(i8),
+    // invalid string name
     #[error("invalid name: {0}")]
     InvalidName(String),
+    // invalid integer key
     #[error("invalid key: {0}")]
     InvalidKey(i32),
 }

src/id.rs

@@ -9,9 +9,12 @@ use serde::{
 
 use crate::error::Error;
 
+/// identifies the verifier that produced the EAR
 #[derive(Debug, PartialEq)]
 pub struct VerifierID {
+    /// uniquely identifies the software build running the verifier
     pub build: String,
+    /// uniquely identifies the organizational unit responsible for this build
     pub developer: String,
 }
 

src/key.rs

@@ -9,6 +9,7 @@ use serde::{
     ser::{Serialize, SerializeMap},
 };
 
+/// public key that is being attested
 #[derive(Debug, PartialEq)]
 pub struct KeyAttestation {
     pub pub_key: Bytes,

src/lib.rs

@@ -99,6 +99,7 @@ pub use self::trust::claim::TrustClaim;
 pub use self::trust::tier::TrustTier;
 pub use self::trust::vector::TrustVector;
 
+/// trustworthiness claims
 pub mod claim {
     pub use super::trust::claim::CRYPTO_VALIDATION_FAILED;
     pub use super::trust::claim::NO_CLAIM;

src/nonce.rs

@@ -137,6 +137,7 @@ impl<'de> Visitor<'de> for OneNonceVisitor {
     }
 }
 
+/// echoed back by the verifier to provide freshness
 #[derive(Debug, PartialEq)]
 pub struct Nonce(Vec<OneNonce>);
 

src/raw.rs

@@ -11,6 +11,7 @@ use serde::ser::{SerializeMap as _, SerializeSeq as _, SerializeTupleVariant as
 
 use crate::base64::Bytes;
 
+/// deserialized raw JSON object or CBOR map
 #[derive(Debug, PartialEq)]
 pub enum RawValue {
     Integer(i64),

src/trust/claim.rs

@@ -333,7 +333,7 @@ pub static SOURCED_DATA_CLAIM_MAP: &Map<i8, ValueDescription<'static>> = &phf_ma
 ///
 /// This is a claim regarding the trustworthiness of one aspect of the attested environment, as
 /// defined in
-/// https://datatracker.ietf.org/doc/html/draft-ietf-rats-ar4si-04#name-trustworthiness-claims
+/// <https://datatracker.ietf.org/doc/html/draft-ietf-rats-ar4si-04#name-trustworthiness-claims>
 #[derive(Debug, Clone, Copy)]
 pub struct TrustClaim {
     /// Claim value