Document (un)marshalling FFI type

Adding comments to the `marshall` and `unmarshall` methods to describe
the type of the bytes produced/expected from the operation.

Also fixing some typos.

Signed-off-by: Ionut Mihalcea <[email protected]>

Author: ionut-arm

tss-esapi/src/structures/attestation/attest.rs

@@ -27,7 +27,7 @@ pub struct Attest {
 }
 
 impl Attest {
-    /// Returns ttestation type
+    /// Returns attestation type
     pub const fn attestation_type(&self) -> AttestationType {
         self.attestation_type
     }
@@ -37,7 +37,7 @@ impl Attest {
         &self.qualified_signer
     }
 
-    /// Retirns the extra data specified by the caller.
+    /// Returns the extra data specified by the caller.
     pub const fn extra_data(&self) -> &Data {
         &self.extra_data
     }
@@ -121,6 +121,7 @@ impl TryFrom<TPMS_ATTEST> for Attest {
 impl Marshall for Attest {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPMS_ATTEST>();
 
+    /// Produce a marshalled [`TPMS_ATTEST`]
     fn marshall(&self) -> Result<Vec<u8>> {
         let mut buffer = vec![0; Self::BUFFER_SIZE];
         let mut offset = 0;
@@ -153,6 +154,7 @@ impl Marshall for Attest {
 }
 
 impl UnMarshall for Attest {
+    /// Unmarshall the structure from [`TPMS_ATTEST`]
     fn unmarshall(marshalled_data: &[u8]) -> Result<Self> {
         let mut dest = TPMS_ATTEST::default();
         let mut offset = 0;

tss-esapi/src/structures/buffers/public.rs

@@ -119,6 +119,7 @@ impl TryFrom<Public> for PublicBuffer {
 impl Marshall for PublicBuffer {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPM2B_PUBLIC>();
 
+    /// Produce a marshalled [`TPM2B_PUBLIC`]
     fn marshall(&self) -> Result<Vec<u8>> {
         let mut buffer = vec![0; Self::BUFFER_SIZE];
         let mut offset = 0;
@@ -151,6 +152,7 @@ impl Marshall for PublicBuffer {
 }
 
 impl UnMarshall for PublicBuffer {
+    /// Unmarshall the structure from [`TPM2B_PUBLIC`]
     fn unmarshall(marshalled_data: &[u8]) -> Result<Self> {
         let mut dest = TPM2B_PUBLIC::default();
         let mut offset = 0;

tss-esapi/src/structures/buffers/sensitive.rs

@@ -118,6 +118,7 @@ impl TryFrom<Sensitive> for SensitiveBuffer {
 impl Marshall for SensitiveBuffer {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPM2B_SENSITIVE>();
 
+    /// Produce a marshalled [`TPM2B_SENSITIVE`]
     fn marshall(&self) -> Result<Vec<u8>> {
         let mut buffer = vec![0; Self::BUFFER_SIZE];
         let mut offset = 0;
@@ -150,6 +151,7 @@ impl Marshall for SensitiveBuffer {
 }
 
 impl UnMarshall for SensitiveBuffer {
+    /// Unmarshall the structure from [`TPM2B_SENSITIVE`]
     fn unmarshall(marshalled_data: &[u8]) -> Result<Self> {
         let mut dest = TPM2B_SENSITIVE::default();
         let mut offset = 0;

tss-esapi/src/structures/tagged/public.rs

@@ -76,7 +76,7 @@ impl PublicBuilder {
         self
     }
 
-    /// Adds the name hash algorithm for the [Public] strucutre
+    /// Adds the name hash algorithm for the [Public] structure
     /// to the builder.
     pub const fn with_name_hashing_algorithm(
         mut self,
@@ -86,7 +86,7 @@ impl PublicBuilder {
         self
     }
 
-    /// Adds the auth policy for the [Public] strucutre
+    /// Adds the auth policy for the [Public] structure
     /// to the builder
     pub fn with_auth_policy(mut self, auth_policy: Digest) -> Self {
         self.auth_policy = Some(auth_policy);
@@ -494,6 +494,9 @@ impl TryFrom<TPMT_PUBLIC> for Public {
 impl Marshall for Public {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPMT_PUBLIC>();
 
+    /// Produce a marshalled [TPMT_PUBLIC]
+    ///
+    /// Note: for [TPM2B_PUBLIC] marshalling use [PublicBuffer][`crate::structures::PublicBuffer]
     fn marshall(&self) -> Result<Vec<u8>> {
         let mut buffer = vec![0; Self::BUFFER_SIZE];
         let mut offset = 0;
@@ -526,6 +529,9 @@ impl Marshall for Public {
 }
 
 impl UnMarshall for Public {
+    /// Unmarshall the structure from [`TPMT_PUBLIC`]
+    ///
+    /// Note: for [TPM2B_PUBLIC] unmarshalling use [PublicBuffer][`crate::structures::PublicBuffer]
     fn unmarshall(marshalled_data: &[u8]) -> Result<Self> {
         let mut dest = TPMT_PUBLIC::default();
         let mut offset = 0;

tss-esapi/src/structures/tagged/sensitive.rs

@@ -166,6 +166,9 @@ impl TryFrom<TPMT_SENSITIVE> for Sensitive {
 impl Marshall for Sensitive {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPMT_SENSITIVE>();
 
+    /// Produce a marshalled [`TPMT_SENSITIVE`]
+    ///
+    /// Note: for [TPM2B_SENSITIVE] marshalling use [SensitiveBuffer][`crate::structures::SensitiveBuffer]
     fn marshall(&self) -> Result<Vec<u8>> {
         let mut buffer = vec![0; Self::BUFFER_SIZE];
         let mut offset = 0;
@@ -198,6 +201,9 @@ impl Marshall for Sensitive {
 }
 
 impl UnMarshall for Sensitive {
+    /// Unmarshall the structure from [`TPMT_SENSITIVE`]
+    ///
+    /// Note: for [TPM2B_SENSITIVE] marshalling use [SensitiveBuffer][`crate::structures::SensitiveBuffer]
     fn unmarshall(marshalled_data: &[u8]) -> Result<Self> {
         let mut dest = TPMT_SENSITIVE::default();
         let mut offset = 0;

tss-esapi/src/structures/tagged/signature.rs

@@ -132,6 +132,7 @@ impl TryFrom<TPMT_SIGNATURE> for Signature {
 impl Marshall for Signature {
     const BUFFER_SIZE: usize = std::mem::size_of::<TPMT_SIGNATURE>();
 
+    /// Produce a marshalled [`TPMT_SIGNATURE`]
     fn marshall(&self) -> Result<Vec<u8>> {
         let tpmt_sig = TPMT_SIGNATURE::try_from(self.clone())?;
         let mut offset = 0;
@@ -164,6 +165,7 @@ impl Marshall for Signature {
 }
 
 impl UnMarshall for Signature {
+    /// Unmarshall the structure from [`TPMT_SIGNATURE`]
     fn unmarshall(public_buffer: &[u8]) -> Result<Self> {
         let mut tpmt_sig = TPMT_SIGNATURE::default();
         let mut offset = 0;

tss-esapi/src/structures/tagged/symmetric.rs

@@ -9,7 +9,7 @@ use crate::{
     Error, Result, WrapperErrorKind,
 };
 use std::convert::{TryFrom, TryInto};
-/// Enum repsesnting the symmetric algorithm definition.
+/// Enum representing the symmetric algorithm definition.
 ///
 /// # Details
 /// This corresponds to TPMT_SYM_DEF.