chore: added rust doc for certificate management trait

harmony/src/modules/cert_manager/capability.rs

@@ -6,22 +6,73 @@ use crate::{
     topology::{PreparationError, PreparationOutcome},
 };
 
-///TODO rust doc explaining issuer, certificate etc
+/// Certificate management capability for a topology.
+///
+/// This trait represents the ability of a topology to provision, manage,
+/// and ensure the availability of TLS certificates.
+///
+/// Implementations may back this capability using different mechanisms,
+/// for example: a Kubernetes controller, an external PKI service, or
+/// platform-specific tooling
+///
+/// ## Concepts
+///
+/// ### Certificate Management System
+/// A certificate management system is responsible for issuing, renewing,
+/// and storing certificates. Before certificates can be created, this
+/// system must be installed and ready to serve requests.
+///
+/// ### Issuer
+/// An Issuer defines how certificates are issued and signed.
+/// It encapsulates trust configuration such as signing keys, certificate
+/// authorities, or external services. Issuers do not represent certificates
+/// themselves, but are referenced by certificate requests.
+///
+/// ### Certificate
+/// A Certificate represents a request for cryptographic identity
+/// material. It references an Issuer and defines the identities the certificate should be valid for,
+/// as well as where the resulting certificate material should be stored.
+///
+/// ## Responsibilities
+///
+/// Implementations of this trait are responsible for:
+///
+/// - Installing the underlying certificate management system
+/// - Ensuring the system is ready before certificates are requested
+/// - Creating Issuers
+/// - Creating Certificates
+///
 #[async_trait]
 pub trait CertificateManagement: Send + Sync {
+    /// Installs the underlying certificate management system for the topology.
+    ///
+    /// Abstracts away installation details
+    /// (e.g., controllers, operators, external services).
     async fn install(&self) -> Result<PreparationOutcome, PreparationError>;
 
+    /// Ensures that the certificate management system is installed and ready.
+    ///
+    /// May verify presence of required components, APIs, or controllers,
+    /// and perform installation if necessary.
     async fn ensure_certificate_management_ready(
         &self,
         config: &CertificateManagementConfig,
     ) -> Result<PreparationOutcome, PreparationError>;
 
+    /// Creates an issuer used to sign certificates.
+    ///
+    /// Abstracts away issuer representation and storage
+    /// (e.g., cluster-scoped resources, external PKI configuration).
     async fn create_issuer(
         &self,
         issuer_name: String,
         config: &CertificateManagementConfig,
     ) -> Result<PreparationOutcome, PreparationError>;
 
+    /// Creates a certificate signed by a previously created issuer.
+    ///
+    /// Abstracts away certificate request, issuance, and storage details
+    /// (e.g., secrets, files, remote APIs).
     async fn create_certificate(
         &self,
         cert_name: String,