docs(tfhe): docstring for LwePrivateFunctionalPackingKeyswitchKey

tfhe/src/core_crypto/entities/lwe_private_functional_packing_keyswitch_key.rs

@@ -2,6 +2,7 @@ use crate::core_crypto::commons::parameters::*;
 use crate::core_crypto::commons::traits::*;
 use crate::core_crypto::entities::*;
 
+/// An [`LWE private functional packing keyswitch key`](`LwePrivateFunctionalPackingKeyswitchKey`).
 #[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 pub struct LwePrivateFunctionalPackingKeyswitchKey<C: Container> {
     data: C,
@@ -23,6 +24,9 @@ impl<T, C: ContainerMut<Element = T>> AsMut<[T]> for LwePrivateFunctionalPacking
     }
 }
 
+/// Return the number of elements in an encryption of an input [`LweSecretKey`] element for a
+/// [`LwePrivateFunctionalPackingKeyswitchKey`] given a [`DecompositionLevelCount`] and output
+/// [`GlweSize`] and [`PolynomialSize`].
 pub fn lwe_pfpksk_input_key_element_encrypted_size(
     decomp_level_count: DecompositionLevelCount,
     output_glwe_size: GlweSize,
@@ -32,6 +36,8 @@ pub fn lwe_pfpksk_input_key_element_encrypted_size(
     decomp_level_count.0 * output_glwe_size.0 * output_polynomial_size.0
 }
 
+/// Return the number of elements in a [`LwePrivateFunctionalPackingKeyswitchKey`] given an input
+/// [`LweSize`], [`DecompositionLevelCount`], output [`GlweSize`], and output [`PolynomialSize`].
 pub fn lwe_pfpksk_size(
     input_lwe_size: LweSize,
     decomp_level_count: DecompositionLevelCount,
@@ -47,6 +53,72 @@ pub fn lwe_pfpksk_size(
 }
 
 impl<Scalar, C: Container<Element = Scalar>> LwePrivateFunctionalPackingKeyswitchKey<C> {
+    /// Create a [`LwePrivateFunctionalPackingKeyswitchKey`] from an existing container.
+    ///
+    /// # Note
+    ///
+    /// This function only wraps a container in the appropriate type. If you want to generate an
+    /// [`LwePrivateFunctionalPackingKeyswitchKey`] you need to use
+    /// [`crate::core_crypto::algorithms::generate_lwe_private_functional_packing_keyswitch_key`] or
+    /// the parallel variant
+    /// [`crate::core_crypto::algorithms::par_generate_lwe_private_functional_packing_keyswitch_key`]
+    /// using this key as output.
+    ///
+    /// This docstring exhibits [`LwePrivateFunctionalPackingKeyswitchKey`] primitives usage.
+    ///
+    /// ```
+    /// use tfhe::core_crypto::prelude::*;
+    ///
+    /// // Define parameters for LwePrivateFunctionalPackingKeyswitchKey creation
+    /// let glwe_size = GlweSize(2);
+    /// let polynomial_size = PolynomialSize(1024);
+    /// let decomp_base_log = DecompositionBaseLog(8);
+    /// let decomp_level_count = DecompositionLevelCount(3);
+    /// let input_lwe_dimension = LweDimension(600);
+    ///
+    /// // Create a new LwePrivateFunctionalPackingKeyswitchKey
+    /// let pfpksk = LwePrivateFunctionalPackingKeyswitchKey::new(
+    ///     0u64,
+    ///     decomp_base_log,
+    ///     decomp_level_count,
+    ///     input_lwe_dimension,
+    ///     glwe_size,
+    ///     polynomial_size,
+    /// );
+    ///
+    /// assert_eq!(
+    ///     pfpksk.output_glwe_key_dimension(),
+    ///     glwe_size.to_glwe_dimension()
+    /// );
+    /// assert_eq!(pfpksk.output_glwe_size(), glwe_size);
+    /// assert_eq!(pfpksk.output_polynomial_size(), polynomial_size);
+    /// assert_eq!(pfpksk.decomposition_base_log(), decomp_base_log);
+    /// assert_eq!(pfpksk.decomposition_level_count(), decomp_level_count);
+    /// assert_eq!(pfpksk.input_lwe_key_dimension(), input_lwe_dimension);
+    ///
+    /// // Demonstrate how to recover the allocated container
+    /// let underlying_container: Vec<u64> = pfpksk.into_container();
+    ///
+    /// // Recreate a key using from_container
+    /// let pfpksk = LwePrivateFunctionalPackingKeyswitchKeyList::from_container(
+    ///     underlying_container,
+    ///     decomp_base_log,
+    ///     decomp_level_count,
+    ///     input_lwe_dimension.to_lwe_size(),
+    ///     glwe_size,
+    ///     polynomial_size,
+    /// );
+    ///
+    /// assert_eq!(
+    ///     pfpksk.output_glwe_key_dimension(),
+    ///     glwe_size.to_glwe_dimension()
+    /// );
+    /// assert_eq!(pfpksk.output_glwe_size(), glwe_size);
+    /// assert_eq!(pfpksk.output_polynomial_size(), polynomial_size);
+    /// assert_eq!(pfpksk.decomposition_base_log(), decomp_base_log);
+    /// assert_eq!(pfpksk.decomposition_level_count(), decomp_level_count);
+    /// assert_eq!(pfpksk.input_lwe_key_dimension(), input_lwe_dimension);
+    /// ```
     pub fn from_container(
         container: C,
         decomp_base_log: DecompositionBaseLog,
@@ -88,30 +160,50 @@ impl<Scalar, C: Container<Element = Scalar>> LwePrivateFunctionalPackingKeyswitc
         }
     }
 
+    /// Return the output key [`GlweDimension`] of the [`LwePrivateFunctionalPackingKeyswitchKey`].
+    ///
+    /// See [`LwePrivateFunctionalPackingKeyswitchKey::from_container`] for usage.
     pub fn output_glwe_key_dimension(&self) -> GlweDimension {
         self.output_glwe_size.to_glwe_dimension()
     }
 
+    /// Return the output [`GlweSize`] of the [`LwePrivateFunctionalPackingKeyswitchKey`].
+    ///
+    /// See [`LwePrivateFunctionalPackingKeyswitchKey::from_container`] for usage.
     pub fn output_glwe_size(&self) -> GlweSize {
         self.output_glwe_size
     }
 
+    /// Return the output [`PolynomialSize`] of the [`LwePrivateFunctionalPackingKeyswitchKey`].
+    ///
+    /// See [`LwePrivateFunctionalPackingKeyswitchKey::from_container`] for usage.
     pub fn output_polynomial_size(&self) -> PolynomialSize {
         self.output_polynomial_size
     }
 
+    /// Return the input key [`LweDimension`] of the [`LwePrivateFunctionalPackingKeyswitchKey`].
+    ///
+    /// See [`LwePrivateFunctionalPackingKeyswitchKey::from_container`] for usage.
     pub fn input_lwe_key_dimension(&self) -> LweDimension {
         LweDimension(self.data.container_len() / self.input_key_element_encrypted_size() - 1)
     }
 
+    /// Return the [`DecompositionLevelCount`] of the [`LwePrivateFunctionalPackingKeyswitchKey`].
+    ///
+    /// See [`LwePrivateFunctionalPackingKeyswitchKey::from_container`] for usage.
     pub fn decomposition_level_count(&self) -> DecompositionLevelCount {
         self.decomp_level_count
     }
 
+    /// Return the [`DecompositionBaseLog`] of the [`LwePrivateFunctionalPackingKeyswitchKey`].
+    ///
+    /// See [`LwePrivateFunctionalPackingKeyswitchKey::from_container`] for usage.
     pub fn decomposition_base_log(&self) -> DecompositionBaseLog {
         self.decomp_base_log
     }
 
+    /// Return the number of elements in an encryption of an input [`LweSecretKey`] element of the
+    /// current [`LwePrivateFunctionalPackingKeyswitchKey`].
     pub fn input_key_element_encrypted_size(&self) -> usize {
         lwe_pfpksk_input_key_element_encrypted_size(
             self.decomp_level_count,
@@ -120,6 +212,8 @@ impl<Scalar, C: Container<Element = Scalar>> LwePrivateFunctionalPackingKeyswitc
         )
     }
 
+    /// Return a view of the [`LwePrivateFunctionalPackingKeyswitchKey`]. This is useful if an
+    /// algorithm takes a view by value.
     pub fn as_view(&self) -> LwePrivateFunctionalPackingKeyswitchKey<&'_ [Scalar]> {
         LwePrivateFunctionalPackingKeyswitchKey::from_container(
             self.as_ref(),
@@ -131,12 +225,15 @@ impl<Scalar, C: Container<Element = Scalar>> LwePrivateFunctionalPackingKeyswitc
     }
 
     /// Consume the entity and return its underlying container.
+    ///
+    /// See [`LwePrivateFunctionalPackingKeyswitchKey::from_container`] for usage.
     pub fn into_container(self) -> C {
         self.data
     }
 }
 
 impl<Scalar, C: ContainerMut<Element = Scalar>> LwePrivateFunctionalPackingKeyswitchKey<C> {
+    /// Mutable variant of [`LwePrivateFunctionalPackingKeyswitchKey::as_view`].
     pub fn as_mut_view(&mut self) -> LwePrivateFunctionalPackingKeyswitchKey<&'_ mut [Scalar]> {
         let decomp_base_log = self.decomp_base_log;
         let decomp_level_count = self.decomp_level_count;
@@ -153,10 +250,23 @@ impl<Scalar, C: ContainerMut<Element = Scalar>> LwePrivateFunctionalPackingKeysw
     }
 }
 
+/// A [`LwePrivateFunctionalPackingKeyswitchKey`] owning the memory for its own storage.
 pub type LwePrivateFunctionalPackingKeyswitchKeyOwned<Scalar> =
     LwePrivateFunctionalPackingKeyswitchKey<Vec<Scalar>>;
 
 impl<Scalar: Copy> LwePrivateFunctionalPackingKeyswitchKeyOwned<Scalar> {
+    /// Create a [`LwePrivateFunctionalPackingKeyswitchKey`] from an existing container.
+    ///
+    /// # Note
+    ///
+    /// This function allocates a vector of the appropriate size and wraps it in the appropriate
+    /// type. If you want to generate an [`LwePrivateFunctionalPackingKeyswitchKey`] you need to use
+    /// [`crate::core_crypto::algorithms::generate_lwe_private_functional_packing_keyswitch_key`] or
+    /// the parallel variant
+    /// [`crate::core_crypto::algorithms::par_generate_lwe_private_functional_packing_keyswitch_key`]
+    /// using this key as output.
+    ///
+    /// See [`LwePrivateFunctionalPackingKeyswitchKey::from_container`] for usage.
     pub fn new(
         fill_with: Scalar,
         decomp_base_log: DecompositionBaseLog,
@@ -230,6 +340,8 @@ impl<C: ContainerMut> ContiguousEntityContainerMut for LwePrivateFunctionalPacki
         Self: 'this;
 }
 
+/// Metadata used in the [`CreateFrom`] implementation to create
+/// [`LwePrivateFunctionalPackingKeyswitchKey`] entities.
 #[derive(Clone, Copy)]
 pub struct LwePrivateFunctionalPackingKeyswitchKeyCreationMetadata(
     pub DecompositionBaseLog,