Fix documentation

hacspec-scrambledb/scrambledb/src/data_transformations.rs

@@ -1,5 +1,5 @@
 //! This module defines ScrambleDB transformations at the level of individual
-//! pieces of data as defined in [crate::data_types].
+//! pieces of data as defined in [`data_types`](crate::data_types).
 //!
 //! These transformations are:
 //! - blinding identifiable and pseudonymous data
@@ -26,14 +26,15 @@ const PSEUDONYMIZATION_CONTEXT: &[u8] = b"CoPRF-Context-Pseudonymization";
 /// generation.
 ///
 /// Inputs:
-/// - bpk: Receiver's blinding public key
-/// - ek: Receiver's public encryption key
-/// - datum: Identifiable datum
-/// - randomness: Random bytes
+/// - `bpk`: Receiver's blinding public key
+/// - `ek`: Receiver's public encryption key
+/// - `datum`: Identifiable data
+/// - `randomness`: Random bytes
 ///
 /// Output:
-/// [BlindedIdentifiableDatum] such that the datum's handle is blinded for
-/// CoPRF evaluation and the datum's value is level-1 encrypted.
+/// [Blinded data](crate::data_types::BlindedIdentifiableData) such that the
+/// datum's handle is blinded for CoPRF evaluation and the datum's value is
+/// level-1 encrypted.
 pub fn blind_identifiable_datum(
     bpk: &BlindingPublicKey,
     ek: &[u8],
@@ -61,16 +62,17 @@ pub fn blind_identifiable_datum(
 /// conversion.
 ///
 /// Inputs:
-/// - store_context: The data store's long term private state including the pseudonym
+/// - `store_context`: The data store's long term private state including the pseudonym
 ///   hardening keys
-/// - bpk: Receiver's blinding public key
-/// - ek: Receiver's public encryption key
-/// - datum: Pseudonymized datum
-/// - randomness: Random bytes
+/// - `bpk`: Receiver's blinding public key
+/// - `ek`: Receiver's public encryption key
+/// - `datum`: Pseudonymized data
+/// - `randomness`: Random bytes
 ///
 /// Output:
-/// [BlindedPseudonymizedDatum] such that the datum's handle is blinded for
-/// CoPRF conversion and the datum's value is level-1 encrypted.
+/// [Blinded pseudonymized data](BlindedPseudonymizedData) such that the
+/// datum's handle is blinded for CoPRF conversion and the datum's value is
+/// level-1 encrypted.
 pub fn blind_pseudonymized_datum(
     store_context: &StoreContext,
     bpk: &BlindingPublicKey,
@@ -97,16 +99,16 @@ pub fn blind_pseudonymized_datum(
 /// Obliviously pseudonymmize a blinded identifiable datum.
 ///
 /// Inputs:
-/// - coprf_context: The converter's CoPRF evaluation context
-/// - bpk: The receiver's blinding public key
-/// - ek: The receiver's public encryption key
-/// - datum: A blinded datum output by [blind_identifiable_datum]
-/// - randomness: Random bytes
+/// - `coprf_context`: The converter's CoPRF evaluation context
+/// - `bpk`: The receiver's blinding public key
+/// - `ek`: The receiver's public encryption key
+/// - `datum`: A blinded datum output by [`blind_identifiable_datum`]
+/// - `randomness`: Random bytes
 ///
 /// Output:
-/// [BlindedPseudonymizedDatum] such that the datum's blinded handle has been
-/// obliviously evaluated to a pseudonym and the datum's value has been level-2
-/// encrypted towards the receiver.
+/// [Blinded pseudonymized data](BlindedPseudonymizedData) such that the
+///  datum's blinded handle has been obliviously evaluated to a pseudonym and
+///  the datum's value has been level-2 encrypted towards the receiver.
 pub fn pseudonymize_blinded_datum(
     coprf_context: &CoPRFEvaluatorContext,
     bpk: &BlindingPublicKey,
@@ -139,16 +141,16 @@ pub fn pseudonymize_blinded_datum(
 /// Obliviously convert a blinded pseudonymous datum to a given target pseudonym key.
 ///
 /// Inputs:
-/// - coprf_context: The Converters CoPRF evaluation context
-/// - bpk: The receiver's blinding public key
-/// - ek: The receiver's public encryption key
-/// - conversion_target: Target pseudonym key identifier
-/// - randomness: Random bytes
+/// - `coprf_context`: The Converters CoPRF evaluation context
+/// - `bpk`: The receiver's blinding public key
+/// - `ek`: The receiver's public encryption key
+/// - `conversion_target`: Target pseudonym key identifier
+/// - `randomness`: Random bytes
 ///
 /// Output:
-/// [BlindedPseudonymizedDatum] such that the datum's pseudonymous handle is
-/// converted to the target pseudonym key and the datum's value is level-2
-/// encrypted towards the receiver.
+/// [Blinded pseudonymized data](BlindedPseudonymizedData)such that the
+/// datum's pseudonymous handle is converted to the target pseudonym key and
+/// the datum's value is level-2 encrypted towards the receiver.
 pub fn convert_blinded_datum(
     coprf_context: &CoPRFEvaluatorContext,
     bpk: &BlindingPublicKey,
@@ -187,15 +189,16 @@ pub fn convert_blinded_datum(
 /// Finalize a blinded pseudonymous datum for storage or analysis.
 ///
 /// Inputs:
-/// - store_context: The data store's long term private state including the
+/// - `store_context`: The data store's long term private state including the
 ///   receiver's coPRF unblinding key, private decryption key, as well as
 ///   pseudonym hardening key
-/// - datum: blinded pseudonymous datum output by [convert_blinded_datum] or
-///   [pseudonymize_blinded_datum]
+/// - `datum`: blinded pseudonymous datum output by [`convert_blinded_datum`] or
+///   [`pseudonymize_blinded_datum`]
 ///
 /// Output:
-/// [PseudonymizedDatum] such that the datum's pseudonymous handle has been
-/// unblinded and hardened and the datum's value has been decrypted.
+/// [Pseudonymized data](PseudonymizedData) such that the datum's pseudonymous
+/// handle has been unblinded and hardened and the datum's value has been
+/// decrypted.
 pub fn finalize_blinded_datum(
     store_context: &StoreContext,
     datum: &BlindedPseudonymizedData,

hacspec-scrambledb/scrambledb/src/data_transformations/double_hpke.rs

@@ -1,5 +1,6 @@
 //! This module defines HPKE-based double encryption and decryption for use in
-//! individual data tranformations as defined in [crate::data_transformations].
+//! individual data tranformations as defined in
+//! [`data_transformations`](crate::data_transformations).
 //!
 //! A plain text data value can be encrypted once to obtain a level-1
 //! encryption of the data value.
@@ -33,15 +34,15 @@ const HPKE_LEVEL_2_INFO: &[u8] = b"Hpke-Level-2";
 /// Level-1 encrypt a plain text data value.
 ///
 /// Inputs:
-/// - data_value: A plain text data value
-/// - ek: The receivers public encryption key
-/// - randomness: Random bytes
+/// - `data_value`: A plain text data value
+/// - `ek`: The receivers public encryption key
+/// - `randomness`: Random bytes
 ///
 /// Output:
 /// A level-1 encrypted data value.
 ///
 /// Raises:
-/// - CorruptedData: If the internal encryption fails.
+/// - `CorruptedData`: If the internal encryption fails.
 ///
 /// Panics:
 /// - on insufficient randomness
@@ -73,16 +74,16 @@ pub(crate) fn hpke_seal_level_1(
 /// Level-2 encrypt a level-1 encrypted data value.
 ///
 /// Inputs:
-/// - data_value: A level-1 encrypted data value
-/// - ek: The receivers public encryption key
-/// - randomness: Random bytes
+/// - `data_value`: A level-1 encrypted data value
+/// - `ek`: The receivers public encryption key
+/// - `randomness`: Random bytes
 ///
 /// Output:
 /// A level-2 encrypted data value.
 ///
 /// Raises:
-/// - InvalidInput: If the input data value is not level-1 encrypted.
-/// - CorruptedData: If the internal encryption fails.
+/// - `InvalidInput`: If the input data value is not level-1 encrypted.
+/// - `CorruptedData`: If the internal encryption fails.
 ///
 /// Panics:
 /// - on insufficient randomness
@@ -118,15 +119,15 @@ pub(crate) fn hpke_seal_level_2(
 /// Decrypt a level-2 encrypted data value.
 ///
 /// Inputs:
-/// - data_value: A Level-2 encrypted data value
-/// - sk: The receiver's decryption key
+/// - `data_value`: A Level-2 encrypted data value
+/// - `sk`: The receiver's decryption key
 ///
 /// Outputs:
 /// A plain text data value.
 ///
 /// Raises:
-/// - InvalidInput: If the input data value is not level-2 encrypted.
-/// - CorruptedData: If the internal decryption fails, e.g. because of
+/// - `InvalidInput`: If the input data value is not level-2 encrypted.
+/// - `CorruptedData`: If the internal decryption fails, e.g. because of
 ///   inconsistent level-1 and level-2 receivers.
 pub(crate) fn hpke_open_level_2(
     data_value: &EncryptedDataValue,

hacspec-scrambledb/scrambledb/src/lib.rs

@@ -269,6 +269,8 @@ pub mod setup;
 pub mod split;
 pub mod join;
 pub mod finalize;
+pub mod data_transformations;
+pub mod data_types;
 
 pub mod error;
 
@@ -277,5 +279,3 @@ pub mod wasm_demo;
 
 #[cfg(test)]
 mod test_util;
-mod data_transformations;
-mod data_types;