In Line Documentation for DIDs crate

bound/kt/src/main/kotlin/web5/sdk/dids/BearerDid.kt

@@ -14,6 +14,9 @@ import web5.sdk.rust.Web5Exception.Exception as RustCoreException
  * Represents a Decentralized Identifier (DID) along with its DID document, key manager, metadata,
  * and convenience functions.
  *
+ * A `BearerDid` encapsulates a DID and its associated DID document. It provides functionality for
+ * working with the DID's keys, managing key signers, and exporting the DID as a PortableDid.
+ *
  * @property did The DID associated with this instance.
  * @property document The DID document associated with this instance.
  * @property keyManager The KeyManager associated with this instance.
@@ -24,6 +27,14 @@ data class BearerDid private constructor(
     val keyManager: KeyManager,
     internal val rustCoreBearerDid: RustCoreBearerDid
 ) {
+    /**
+     * Constructs a new [BearerDid] from the provided DID, document, and key manager.
+     *
+     * @param did The DID.
+     * @param document The DID document.
+     * @param keyManager The key manager used for key storage and signing.
+     * @throws Web5Exception If an error occurs during the creation process.
+     */
     constructor(did: Did, document: Document, keyManager: KeyManager) : this(
         did,
         document,
@@ -41,9 +52,14 @@ data class BearerDid private constructor(
 
     companion object {
         /**
-         * Constructs a BearerDid instance from a PortableDid.
+         * Constructs a [BearerDid] instance from a [PortableDid].
          *
-         * @param portableDid The PortableDid.
+         * This method allows you to create a `BearerDid` from a portable representation of a DID, typically used for
+         * importing or exporting DIDs across different systems or platforms.
+         *
+         * @param portableDid The [PortableDid] object.
+         * @return A new instance of [BearerDid].
+         * @throws Web5Exception If an error occurs during the creation process.
          */
         fun fromPortableDid(portableDid: PortableDid): BearerDid {
             try {
@@ -54,6 +70,12 @@ data class BearerDid private constructor(
             }
         }
 
+        /**
+         * Constructs a [BearerDid] from a RustCore `BearerDid`.
+         *
+         * @param rustCoreBearerDid The RustCore `BearerDid` object.
+         * @return A new instance of [BearerDid].
+         */
         internal fun fromRustCoreBearerDid(rustCoreBearerDid: RustCoreBearerDid): BearerDid {
             val rustCoreBearerDidData = rustCoreBearerDid.getData()
             return BearerDid(
@@ -67,7 +89,19 @@ data class BearerDid private constructor(
     /**
      * Returns a signer for the DID.
      *
-     * @return Signer The signer for the DID.
+     * This method retrieves a signer associated with the specified verification method. The signer can be used
+     * to cryptographically sign data using the DID's key material.
+     *
+     * @param verificationMethodId The ID of the verification method to use.
+     * @return A [Signer] instance for signing data.
+     * @throws Web5Exception If an error occurs during signer retrieval.
+     *
+     * @example
+     * ```
+     * val bearerDid = BearerDid(did, document, keyManager)
+     * val signer = bearerDid.getSigner("did:example:123#key-1")
+     * val signature = signer.sign(data)
+     * ```
      */
     fun getSigner(verificationMethodId: String): Signer {
         try {
@@ -79,7 +113,20 @@ data class BearerDid private constructor(
     }
 
     /**
-     * Returns the BearerDid represented as a PortableDid
+     * Returns the BearerDid represented as a [PortableDid].
+     *
+     * This method exports the `BearerDid` as a `PortableDid`, allowing for easy transport and storage
+     * across different systems or platforms.
+     *
+     * @param keyExporter The key exporter to use for exporting the private keys.
+     * @return A [PortableDid] object representing the exported DID.
+     * @throws Web5Exception If an error occurs during the export process.
+     *
+     * @example
+     * ```
+     * val bearerDid = BearerDid(did, document, keyManager)
+     * val portableDid = bearerDid.toPortableDid(keyExporter)
+     * ```
      */
     fun toPortableDid(keyExporter: KeyExporter): PortableDid {
         try {

bound/kt/src/main/kotlin/web5/sdk/dids/Did.kt

@@ -7,6 +7,19 @@ import web5.sdk.rust.Web5Exception.Exception as RustCoreException
 
 /**
  * Representation of a [DID Core Identifier](https://www.w3.org/TR/did-core/#identifiers).
+ *
+ * A `Did` represents a Decentralized Identifier (DID), which uniquely identifies a subject (such as a person,
+ * organization, device, etc.). This class allows the parsing of a DID URI, as well as the transformation
+ * to and from Rust core data.
+ *
+ * @property uri The complete DID URI.
+ * @property url The parsed URL associated with the DID.
+ * @property method The DID method (e.g., `jwk`, `dht`, `web`), which defines how the DID is resolved.
+ * @property id The method-specific identifier of the DID.
+ * @property params Optional method-specific parameters present in the DID URI.
+ * @property path Optional path component in the DID URI.
+ * @property query Optional query component in the DID URI.
+ * @property fragment Optional fragment component in the DID URI.
  */
 data class Did (
     val uri: String,
@@ -19,6 +32,22 @@ data class Did (
     val fragment: String? = null
 ) {
     companion object {
+        /**
+         * Parses a DID URI into a `Did` object.
+         *
+         * This method constructs a `Did` instance by using Rust core functions to parse the provided DID URI.
+         * It retrieves the underlying data and converts it into a Kotlin `Did` object.
+         *
+         * @param uri The DID URI to parse.
+         * @return A `Did` object representing the parsed DID URI.
+         * @throws Web5Exception If parsing the DID URI fails.
+         *
+         * @example
+         * ```
+         * val did = Did.parse("did:example:123456")
+         * println(did.method)  // Output: "example"
+         * ```
+         */
         fun parse(uri: String): Did {
             try {
                 val rustCoreDid = RustCoreDid(uri)
@@ -46,4 +75,4 @@ data class Did (
     internal fun toRustCoreDidData(): RustCoreDidData {
         return RustCoreDidData(uri, url, method, id, params, path, query, fragment)
     }
-}
+}

bound/kt/src/main/kotlin/web5/sdk/dids/Document.kt

@@ -6,6 +6,22 @@ import web5.sdk.rust.Web5Exception.Exception as RustCoreException
 
 /**
  * Representation of a [DID Document](https://github.com/TBD54566975/web5-spec/blob/main/spec/did.md).
+ *
+ * A `Document` represents the full DID document, which is a set of data describing a DID subject, including
+ * public keys, authentication mechanisms, services, and more. This class provides functionality for converting
+ * the document to and from JSON format, as well as converting it to and from Rust core data.
+ *
+ * @property id The DID URI representing the subject of the DID document.
+ * @property context A list of URIs defining the schema version used in the document (optional).
+ * @property controller A list of entities authorized to make changes to the DID document (optional).
+ * @property alsoKnownAs A list of alternative identifiers for the DID subject (optional).
+ * @property verificationMethod A list of cryptographic public keys for authentication and authorization.
+ * @property authentication Methods for authenticating the DID subject (optional).
+ * @property assertionMethod Methods for expressing claims, such as issuing Verifiable Credentials (optional).
+ * @property keyAgreement Methods for establishing secure communication channels (optional).
+ * @property capabilityInvocation Methods used by the DID subject to invoke cryptographic capabilities (optional).
+ * @property capabilityDelegation Methods used by the DID subject to delegate cryptographic capabilities (optional).
+ * @property service A list of services provided by the DID subject (optional).
  */
 data class Document(
     val id: String,
@@ -21,6 +37,23 @@ data class Document(
     val service: List<Service>?
 ) {
     companion object {
+        /**
+         * Converts a JSON string into a `Document` object.
+         *
+         * This method parses a JSON string and constructs a `Document` instance from the parsed data.
+         * It uses Rust core functionality to handle the underlying parsing.
+         *
+         * @param json The JSON string representing the DID document.
+         * @return A `Document` object.
+         * @throws Web5Exception If parsing the JSON string fails.
+         *
+         * @example
+         * ```
+         * val jsonString = """{ "id": "did:example:123", "verificationMethod": [...] }"""
+         * val document = Document.fromJsonString(jsonString)
+         * println(document.id)  // Output: "did:example:123"
+         * ```
+         */
         fun fromJsonString(json: String): Document {
             try {
                 return fromRustCore(web5.sdk.rust.Document.fromJsonString(json).getData())
@@ -46,6 +79,21 @@ data class Document(
         }
     }
 
+    /**
+     * Converts the `Document` object to a JSON string.
+     *
+     * This method serializes the `Document` instance into a JSON string using Rust core functionality.
+     *
+     * @return The JSON string representing the DID document.
+     * @throws Web5Exception If serialization to JSON fails.
+     *
+     * @example
+     * ```
+     * val document = Document(id = "did:example:123", verificationMethod = listOf(...))
+     * val jsonString = document.toJsonString()
+     * println(jsonString)  // Output: JSON representation of the document
+     * ```
+     */
     fun toJsonString(): String {
         try {
             return web5.sdk.rust.Document(toRustCore()).toJsonString()
@@ -71,6 +119,17 @@ data class Document(
     }
 }
 
+/**
+ * Represents a verification method within a DID document.
+ *
+ * A `VerificationMethod` describes a cryptographic public key that can be used to authenticate or authorize
+ * interactions with the DID subject.
+ *
+ * @property id The ID of the verification method.
+ * @property type The type of verification method (e.g., "JsonWebKey").
+ * @property controller The controller of the verification method.
+ * @property publicKeyJwk The public key in JWK format.
+ */
 data class VerificationMethod(
     val id: String,
     val type: String,
@@ -95,6 +154,16 @@ data class VerificationMethod(
     }
 }
 
+/**
+ * Represents a service within a DID document.
+ *
+ * A `Service` describes an endpoint that can be used to interact with the DID subject, such as
+ * communication, discovery, or storage services.
+ *
+ * @property id The ID of the service.
+ * @property type The type of service.
+ * @property serviceEndpoint A list of endpoints where the service can be accessed.
+ */
 data class Service(
     val id: String,
     val type: String,

bound/kt/src/main/kotlin/web5/sdk/dids/PortableDid.kt

@@ -5,12 +5,36 @@ import web5.sdk.crypto.keys.Jwk
 import web5.sdk.rust.PortableDid as RustCorePortableDid
 import web5.sdk.rust.Web5Exception.Exception as RustCoreException
 
+/**
+ * Represents a portable DID (Decentralized Identifier) and its associated data, such as the DID document and private keys.
+ *
+ * A `PortableDid` allows the DID, its document, and associated private keys to be transported, saved, or shared
+ * across systems in a portable format.
+ *
+ * @property didUri The DID URI associated with the portable DID.
+ * @property document The DID document associated with the portable DID.
+ * @property privateKeys A list of private keys (JWK format) associated with the DID.
+ */
 data class PortableDid private constructor(
     val didUri: String,
     val document: Document,
     val privateKeys: List<Jwk>,
     internal val rustCorePortableDid: RustCorePortableDid
 ) {
+    /**
+     * Constructs a `PortableDid` instance from a DID URI, document, and list of private keys.
+     *
+     * @param didUri The DID URI associated with the portable DID.
+     * @param document The DID document associated with the portable DID.
+     * @param privateKeys A list of private keys (JWK format) associated with the DID.
+     * @throws Web5Exception If there is an error constructing the RustCorePortableDid object.
+     *
+     * @example
+     * ```
+     * val portableDid = PortableDid(didUri, document, privateKeys)
+     * println(portableDid.didUri)  // Output: The DID URI
+     * ```
+     */
     constructor(didUri: String, document: Document, privateKeys: List<Jwk>) : this(
         didUri,
         document,
@@ -28,9 +52,20 @@ data class PortableDid private constructor(
 
     companion object {
         /**
-         * Constructs a PortableDid from a JSON string.
+         * Constructs a `PortableDid` from a JSON string.
+         *
+         * This method parses a JSON string and constructs a `PortableDid` instance using Rust core functionality.
+         *
+         * @param json The JSON string representing the portable DID.
+         * @return A `PortableDid` object.
+         * @throws Web5Exception If there is an error parsing the JSON string.
          *
-         * @param json The JSON string.
+         * @example
+         * ```
+         * val jsonString = """{ "didUri": "did:example:123", "document": {...}, "privateKeys": [...] }"""
+         * val portableDid = PortableDid.fromJsonString(jsonString)
+         * println(portableDid.didUri)  // Output: The DID URI
+         * ```
          */
         fun fromJsonString(json: String): PortableDid {
             try {
@@ -53,7 +88,19 @@ data class PortableDid private constructor(
     }
 
     /**
-     * Serializes a PortableDid to a JSON string.
+     * Serializes the `PortableDid` to a JSON string.
+     *
+     * This method converts the `PortableDid` instance into a JSON string using Rust core functionality.
+     *
+     * @return A JSON string representing the portable DID.
+     * @throws Web5Exception If serialization to JSON fails.
+     *
+     * @example
+     * ```
+     * val portableDid = PortableDid(didUri, document, privateKeys)
+     * val jsonString = portableDid.toJsonString()
+     * println(jsonString)  // Output: JSON representation of the portable DID
+     * ```
      */
     fun toJsonString(): String {
         try {
@@ -62,4 +109,4 @@ data class PortableDid private constructor(
             throw Web5Exception.fromRustCore(e)
         }
     }
-}
+}