Add crate-level documentation for ssi-dids (#607)

crates/dids/Cargo.toml

@@ -33,4 +33,7 @@ did-method-key.workspace = true
 did-pkh.workspace = true
 did-tz.workspace = true
 did-web.workspace = true
-thiserror.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+async-std = { workspace = true, features = ["attributes"] }

crates/dids/core/src/did/url.rs

@@ -36,14 +36,15 @@ impl DIDURL {
     ///
     /// Fails if the data is not a DID URL according to the
     /// [DID Syntax](https://w3c.github.io/did-core/#did-url-syntax).
-    pub fn new(data: &[u8]) -> Result<&Self, InvalidDIDURL<&[u8]>> {
+    pub fn new<T: ?Sized + AsRef<[u8]>>(did_url: &T) -> Result<&Self, InvalidDIDURL<&T>> {
+        let data = did_url.as_ref();
         match Self::validate(data) {
             Ok(()) => Ok(unsafe {
                 // SAFETY: DID is a transparent wrapper over `[u8]`,
                 //         and we just checked that `data` is a DID URL.
                 std::mem::transmute::<&[u8], &Self>(data)
             }),
-            Err(e) => Err(InvalidDIDURL(data, e)),
+            Err(e) => Err(InvalidDIDURL(did_url, e)),
         }
     }
 

crates/dids/core/src/resolution.rs

@@ -25,38 +25,51 @@ pub use http::*;
 /// [DID URL dereferencing](DIDResolver::dereference).
 pub const MEDIA_TYPE_URL: &str = "text/url";
 
+/// DID resolution error.
+///
+/// Error raised by the [`DIDResolver::resolve`] method.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
+    /// DID method is not supported by this resolver.
     #[error("DID method `{0}` not supported")]
     MethodNotSupported(String),
 
+    /// DID document could not be found.
     #[error("DID document not found")]
     NotFound,
 
+    /// Resolver doesn't know what representation to use for the DID document.
     #[error("no representation specified")]
     NoRepresentation,
 
+    /// Requested DID document representation is not supported.
     #[error("DID representation `{0}` not supported")]
     RepresentationNotSupported(String),
 
+    /// Invalid data provided to the resolver.
     #[error(transparent)]
     InvalidData(InvalidData),
 
+    /// Invalid method-specific identifier.
     #[error("invalid method specific identifier: {0}")]
     InvalidMethodSpecificId(String),
 
+    /// Invalid resolution options.
     #[error("invalid options")]
     InvalidOptions,
 
+    /// Internal resolver-specific error.
     #[error("DID resolver internal error: {0}")]
     Internal(String),
 }
 
 impl Error {
+    /// Creates a new internal error.
     pub fn internal(error: impl ToString) -> Self {
         Self::Internal(error.to_string())
     }
 
+    /// Returns the error kind.
     pub fn kind(&self) -> ErrorKind {
         match self {
             Self::MethodNotSupported(_) => ErrorKind::MethodNotSupported,
@@ -77,6 +90,9 @@ impl From<representation::Unknown> for Error {
     }
 }
 
+/// Resolution error kind.
+///
+/// Each resolution [`Error`] has a kind provided by the [`Error::kind`] method.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum ErrorKind {
     MethodNotSupported,
@@ -116,10 +132,18 @@ impl<T: DIDResolverByMethod> DIDResolver for T {
     }
 }
 
-/// A [DID resolver](https://www.w3.org/TR/did-core/#dfn-did-resolvers),
-/// implementing the [DID Resolution](https://www.w3.org/TR/did-core/#did-resolution)
-/// [algorithm](https://w3c-ccg.github.io/did-resolution/#resolving-algorithm) and
-/// optionally [DID URL Dereferencing](https://www.w3.org/TR/did-core/#did-url-dereferencing).
+/// [DID resolver](https://www.w3.org/TR/did-core/#dfn-did-resolvers).
+///
+/// Any type implementing the [DID Resolution](https://www.w3.org/TR/did-core/#did-resolution)
+/// [algorithm](https://w3c-ccg.github.io/did-resolution/#resolving-algorithm)
+/// through the [`resolve`](DIDResolver::resolve) method
+/// and the [DID URL Dereferencing](https://www.w3.org/TR/did-core/#did-url-dereferencing)
+/// algorithm through the [`dereference`](DIDResolver::dereference) method.
+///
+/// This library provides the [`AnyDidMethod`] that implements this trait
+/// by grouping various DID method implementations.
+///
+/// [`AnyDidMethod`]: <../dids/struct.AnyDidMethod.html>
 pub trait DIDResolver {
     /// Resolves a DID representation.
     ///

crates/dids/methods/pkh/src/lib.rs

@@ -135,6 +135,8 @@ const REFERENCE_TEZOS_MAINNET: &str = "NetXdQprcVkpaWU";
 const REFERENCE_SOLANA_MAINNET: &str = "4sGjMW1sUnHzSxGspuhpqLDx6wiyjNtZ";
 
 /// did:pkh DID Method
+///
+/// See: <https://github.com/w3c-ccg/did-pkh/blob/main/did-pkh-method-draft.md>
 pub struct DIDPKH;
 
 type ResolutionResult = Result<(Document, JsonLdContext), Error>;