docs: add comprehensive Rustdoc comments and fix inaccurate help text

Add module-level documentation (//!) and doc comments (///) to all
source files to support `cargo doc` and prepare for `cargo rdme`
README generation.

Changes per file:
- main.rs: Add top-level crate documentation with usage overview and
  subcommand table; add #![deny(missing_docs)] to enforce documentation
  on public items; fix SnpGuestCmd variant descriptions to match actual
  behavior
- report.rs: Document ReportArgs fields accurately; fix --random help
  (was misleading about default file path); fix --platform help to
  describe vTPM retrieval on Azure CVMs
- certs.rs: Document CertPaths, CertFormat, CertificatesArgs, and all
  public functions
- fetch.rs: Document FetchCmd, Endorsement, ProcType enums; document
  all submodule Args structs and functions; improve fetch ca/vcek/crl
  argument descriptions
- verify.rs: Fix critical help text errors from issue virtee#132: --tcb now
  correctly described as "verify TCB only (skip signature)" instead of
  "run TCB verification exclusively"; --signature now correctly
  described as "verify signature only (skip TCB)" instead of "run
  signature verification exclusively"; document decode_hex_or_decimal
  behavior mismatch (issue virtee#135); document all verification functions
- display.rs: Document DisplayCmd and subcommand functions
- key.rs: Document KeyArgs with accurate Guest Field Select bit
  descriptions; document message version auto-selection behavior
- ok.rs: Document SEV status MSR bitfield and capability test framework
- preattestation.rs: Document all generate subcommands (measurement,
  ovmf-hash, id-block, key-digest) with accurate argument descriptions
- clparser/mod.rs: Document auto-radix parser and FromStrRadix trait
- hyperv/mod.rs: Document Hyper-V detection logic and vTPM report
  retrieval

Source of truth: actual code behavior on main branch and the corrected
README.md from PR virtee#139 (docs-overhaul branch).

https://claude.ai/code/session_01YFz1JMARmZYNFwTQ6juM7Z

Author: claude

src/certs.rs

@@ -1,5 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
-// This file contains code related to managing certificates. It defines a structure for managing certificate paths (`CertPaths`) and functions for obtaining extended certificates from the AMD Secure Processor.
+
+//! Certificate management for the `certificates` subcommand.
+//!
+//! This module provides structures and functions for requesting certificates
+//! cached in hypervisor memory via the AMD Secure Processor
+//! (`SNP_GET_EXT_REPORT` ioctl), converting certificate formats (PEM/DER),
+//! and writing certificates to disk.
 
 use crate::fetch::Endorsement;
 
@@ -17,18 +23,25 @@ use sev::{
     firmware::{guest::Firmware, host::CertType},
 };
 
+/// Paths to the three certificates that form an SNP certificate chain:
+/// ARK (AMD Root Key), ASK (AMD SEV Key) or ASVK (AMD SEV-VLEK Key),
+/// and VCEK (Versioned Chip Endorsement Key) or VLEK (Versioned Loaded Endorsement Key).
 pub struct CertPaths {
+    /// Path to the AMD Root Key certificate.
     pub ark_path: PathBuf,
+    /// Path to the AMD SEV Key (or ASVK for VLEK chains) certificate.
     pub ask_path: PathBuf,
+    /// Path to the VCEK or VLEK certificate.
     pub vek_path: PathBuf,
 }
 
+/// Supported certificate encoding formats.
 #[derive(ValueEnum, Clone, Copy)]
 pub enum CertFormat {
-    /// Certificates are encoded in PEM format.
+    /// PEM (Privacy-Enhanced Mail) encoding.
     Pem,
 
-    /// Certificates are encoded in DER format.
+    /// DER (Distinguished Encoding Rules) binary encoding.
     Der,
 }
 
@@ -52,7 +65,10 @@ impl FromStr for CertFormat {
     }
 }
 
-// Function that will convert a cert path into a snp Certificate
+/// Read a certificate file and convert it into an SNP [`Certificate`].
+///
+/// If `cert_path` is empty, falls back to looking in `./certs/` for
+/// `{cert_type}.pem` or `{cert_type}.der`.
 pub fn convert_path_to_cert(
     cert_path: &PathBuf,
     cert_type: &str,
@@ -88,7 +104,7 @@ pub fn convert_path_to_cert(
     Ok(Certificate::from_bytes(&buf)?)
 }
 
-// Tryfrom function that takes in 3 certificate paths returns a snp Certificate Chain
+/// Build an SNP [`Chain`] from three certificate file paths (ARK, ASK/ASVK, VCEK/VLEK).
 impl TryFrom<CertPaths> for Chain {
     type Error = anyhow::Error;
     fn try_from(content: CertPaths) -> Result<Self, Self::Error> {
@@ -117,7 +133,11 @@ impl TryFrom<CertPaths> for Chain {
     }
 }
 
-// Function used to write provided cert into desired directory.
+/// Write a certificate to a file in the specified encoding format.
+///
+/// The filename is derived from the certificate type and encoding
+/// (e.g., `vcek.pem`, `ark.der`). For VLEK endorsement with an ASK
+/// cert type, the file is named `asvk`.
 pub fn write_cert(
     path: &Path,
     cert_type: &CertType,
@@ -164,17 +184,26 @@ pub fn write_cert(
     Ok(())
 }
 
+/// CLI arguments for the `certificates` subcommand.
+///
+/// Requests certificates from the hypervisor extended memory via the AMD
+/// Secure Processor and stores them in the specified directory.
 #[derive(Parser)]
 pub struct CertificatesArgs {
-    /// Specify encoding to use for certificates.
+    /// Certificate encoding format (PEM or DER).
     #[arg(value_name = "encoding", required = true, ignore_case = true)]
     pub encoding: CertFormat,
 
-    /// Directory to store certificates in. Required if requesting an extended-report.
+    /// Directory to store the certificates in. Created if it does not exist.
     #[arg(value_name = "certs-dir", required = true)]
     pub certs_dir: PathBuf,
 }
 
+/// Request extended certificates from the AMD Secure Processor and write them to disk.
+///
+/// Uses `SNP_GET_EXT_REPORT` to obtain certificates cached in the hypervisor
+/// extended memory. Each certificate is written to the specified directory in the
+/// chosen encoding format.
 pub fn get_ext_certs(args: CertificatesArgs) -> Result<()> {
     let mut sev_fw: Firmware = Firmware::open().context("failed to open SEV firmware device.")?;
 

src/clparser/mod.rs

@@ -1,8 +1,20 @@
 // SPDX-License-Identifier: Apache-2.0
-// This file contains custom u32/u64 parsers for supporting decimal, hexadecimal and binary formats.
+
+//! Custom integer parsers for CLI arguments supporting multiple radix formats.
+//!
+//! Provides a clap-compatible value parser that accepts integers in:
+//! - Decimal (e.g., `63`)
+//! - Hexadecimal with `0x` prefix (e.g., `0x3f`)
+//! - Binary with `0b` prefix (e.g., `0b111111`)
 
 use std::num::ParseIntError;
 
+/// Parse an integer string with automatic radix detection.
+///
+/// Supported formats:
+/// - `0x...` — hexadecimal
+/// - `0b...` — binary
+/// - anything else — decimal
 pub fn parse_int_auto_radix<T>(s: &str) -> Result<T, ParseIntError>
 where
     T: FromStrRadix,
@@ -16,7 +28,11 @@ where
     }
 }
 
+/// Trait for parsing integers from a string with a given radix.
+///
+/// Implemented for [`u32`] and [`u64`].
 pub trait FromStrRadix: Sized {
+    /// Parse `src` as an integer in the given `radix` (2, 10, or 16).
     fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError>;
 }
 

src/display.rs

@@ -1,18 +1,25 @@
 // SPDX-License-Identifier: Apache-2.0
-// This file contains the subcommands for displaying attestation reports and derived keys.
+
+//! Display attestation reports and derived keys in human-readable form.
+//!
+//! This module provides the `display` subcommand family:
+//! - `display report` — Print an attestation report's contents to the terminal.
+//! - `display key` — Print a derived key in hex format to the terminal.
 
 use super::*;
 use std::path::PathBuf;
 
+/// Subcommands for displaying attestation data in human-readable form.
 #[derive(Subcommand)]
 pub enum DisplayCmd {
-    /// Display an attestation report in console.
+    /// Print the contents of an attestation report to the terminal.
     Report(report_display::Args),
 
-    /// Display the derived key in console.
+    /// Print a derived key in hex format to the terminal.
     Key(key_display::Args),
 }
 
+/// Dispatch to the appropriate display subcommand handler.
 pub fn cmd(cmd: DisplayCmd, quiet: bool) -> Result<()> {
     match cmd {
         DisplayCmd::Report(args) => report_display::display_attestation_report(args, quiet),
@@ -22,14 +29,15 @@ pub fn cmd(cmd: DisplayCmd, quiet: bool) -> Result<()> {
 mod report_display {
     use super::*;
 
+    /// CLI arguments for `display report`.
     #[derive(Parser)]
     pub struct Args {
-        /// Path to attestation report to display.
+        /// Path to the attestation report file to display.
         #[arg(value_name = "att-report-path", required = true)]
         pub att_report_path: PathBuf,
     }
 
-    // Print attestation report in console
+    /// Read and print an attestation report to the console.
     pub fn display_attestation_report(args: Args, quiet: bool) -> Result<()> {
         let att_report = report::read_report(args.att_report_path)
             .context("Could not open attestation report")?;
@@ -45,14 +53,15 @@ mod report_display {
 mod key_display {
     use super::*;
 
+    /// CLI arguments for `display key`.
     #[derive(Parser)]
     pub struct Args {
-        /// Path of key to be displayed.
+        /// Path to the derived key file to display.
         #[arg(value_name = "key-path", required = true)]
         pub key_path: PathBuf,
     }
 
-    // Print derived key in console
+    /// Read and print a derived key in hex format (16 bytes per line).
     pub fn display_derived_key(args: Args, quiet: bool) -> Result<()> {
         let key_report = key::read_key(args.key_path).context("Could not open key")?;
 
@@ -62,7 +71,6 @@ mod key_display {
                 if (i % 16) == 0 {
                     keydata.push('\n');
                 }
-                //Displaying key in Hex format
                 keydata.push_str(&format!("{byte:02x} "));
             }
             keydata.push('\n');