Add docstrings to examples (#19)

* Update changelog * Add missing docstrings to examples
JuliaCrypto · Mar 5, 2021 · b76dd18 · b76dd18
1 parent 76ba60d
commit b76dd18
Show file tree

Hide file tree

Showing 6 changed files with 202 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,9 @@ This file only tracks changes at a very high, summarized level, omitting patch r
 ## SEAL dev
 * ...
 
+## SEAL v0.4.0
+* Update the wrapper to support SEAL v3.6
+
 ## SEAL v0.3.0
 * Add `examples/6_serialization.jl` and `examples/7_performance.jl` and all corresponding
   functionality in the library itself

diff --git a/examples/2_encoders.jl b/examples/2_encoders.jl
@@ -3,6 +3,19 @@ include("utilities.jl")
 using SEAL
 using Printf
 
+
+"""
+    example_batch_encoder()
+
+Example to demonstrate encoding and decoding vectors of integers with the BFV scheme.
+This function is based on the file `native/examples/2_encoders.cpp` of the original
+SEAL library and should yield the exact same output.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/2_encoders.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/2_encoders.cpp)
+
+See also: [`example_ckks_encoder`](@ref), [`example_encoders`](@ref)
+"""
 function example_batch_encoder()
   print_example_banner("Example: Encoders / Batch Encoder")
 
@@ -92,6 +105,19 @@ function example_batch_encoder()
   print_matrix(pod_result, row_size)
 end
 
+
+"""
+    example_ckks_encoder()
+
+Example to demonstrate encoding and decoding vectors of floating point values with the CKKS scheme.
+This function is based on the file `native/examples/2_encoders.cpp` of the original
+SEAL library and should yield the exact same output.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/2_encoders.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/2_encoders.cpp)
+
+See also: [`example_batch_encoder`](@ref), [`example_encoders`](@ref)
+"""
 function example_ckks_encoder()
   print_example_banner("Example: Encoders / CKKS Encoder")
 
@@ -156,6 +182,20 @@ function example_ckks_encoder()
 
 end
 
+
+"""
+    example_encoders()
+
+Demonstrate how vectors of integers (BFV) or floating point values (CKKS) can be encoded/decoded
+with the BFV and CKKS schemes.
+This function is based on the file `native/examples/2_encoders.cpp` of the original
+SEAL library and should yield the exact same output.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/2_encoders.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/2_encoders.cpp)
+
+See also: [`example_batch_encoder`](@ref), [`example_ckks_encoder`](@ref)
+"""
 function example_encoders()
   print_example_banner("Example: Encoders")
 

diff --git a/examples/3_levels.jl b/examples/3_levels.jl
@@ -4,6 +4,18 @@ using SEAL
 using Printf
 
 
+"""
+    example_levels()
+
+Illustrate the concept of levels in the BFV and CKKS schemes.
+This function is based on the file `native/examples/3_levels.cpp` of the original
+SEAL library and should yield the exact same output.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/3_levels.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/3_levels.cpp)
+
+See also: [`example_bfv_basics`](@ref), [`example_ckks_basics`](@ref)
+"""
 function example_levels()
   print_example_banner("Example: Levels")
 

diff --git a/examples/5_rotation.jl b/examples/5_rotation.jl
@@ -173,6 +173,17 @@ function example_rotation_ckks()
   return
 end
 
+
+"""
+    example_rotation()
+
+Perform some rotation on data encryped with the BFV and CKKS schemes. This routine is based on the
+file `native/examples/5_rotation.cpp` of the original SEAL library and should yield the exact same
+output.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/5_rotation.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/5_rotation.cpp)
+"""
 function example_rotation()
   print_example_banner("Example: Rotation")
 

diff --git a/examples/6_serialization.jl b/examples/6_serialization.jl
@@ -4,6 +4,19 @@ using SEAL
 using Printf
 
 
+"""
+    example_serialization()
+
+Show example for how to use serialization in a client-server setup, where only the client knows the
+secret key and the servers does not have knowledge of any unencrypted data.
+This function is based on the file `native/examples/6_serialization.cpp` of the original
+SEAL library and should yield the exact same output, except for differences in compression ratios.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/6_serialization.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/6_serialization.cpp)
+
+See also: [`example_bfv_basics`](@ref), [`example_ckks_basics`](@ref)
+"""
 function example_serialization()
   print_example_banner("Example: Serialization")
 

diff --git a/examples/7_performance.jl b/examples/7_performance.jl
@@ -5,6 +5,23 @@ using Printf
 using Random
 
 
+"""
+    bfv_performance_test(context)
+
+Perform multiple performance tests with the BFV scheme for the SEAL encryption context given in
+`context`.
+
+This function is based on the file `native/examples/7_performance.cpp` of the original
+SEAL library and should yield the exact same output, except (of course) for the actual performance
+numbers.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp)
+
+See also: [`example_performance_test`](@ref),
+          [`example_ckks_performance_default`](@ref), [`example_ckks_performance_custom`](@ref),
+          [`bfv_performance_test`](@ref)
+"""
 function bfv_performance_test(context)
   print_parameters(context)
   println()
@@ -190,6 +207,24 @@ function bfv_performance_test(context)
   println("Average compressed (Zstandard) serialize ciphertext: ", avg_serialize_zstd, " microseconds")
 end
 
+
+"""
+    ckks_performance_test(context)
+
+Perform multiple performance tests with the CKKS scheme for the SEAL encryption context given in
+`context`.
+
+This function is based on the file `native/examples/7_performance.cpp` of the original
+SEAL library and should yield the exact same output, except (of course) for the actual performance
+numbers.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp)
+
+See also: [`example_performance_test`](@ref),
+          [`example_ckks_performance_default`](@ref), [`example_ckks_performance_custom`](@ref),
+          [`bfv_performance_test`](@ref)
+"""
 function ckks_performance_test(context)
   print_parameters(context)
   println()
@@ -368,6 +403,23 @@ function ckks_performance_test(context)
   flush(stdout)
 end
 
+
+"""
+    example_bfv_performance_default()
+
+Perform multiple performance tests of the BFV scheme for several polynomial modulus degrees.
+
+This function is based on the file `native/examples/7_performance.cpp` of the original
+SEAL library and should yield the exact same output, except (of course) for the actual performance
+numbers.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp)
+
+See also: [`example_performance_test`](@ref), [`example_bfv_performance_custom`](@ref),
+          [`bfv_performance_test`](@ref),
+          [`example_ckks_performance_default`](@ref)
+"""
 function example_bfv_performance_default()
   print_example_banner("BFV Performance Test with Degrees: 4096, 8192, and 16384")
 
@@ -402,6 +454,24 @@ function example_bfv_performance_default()
   # bfv_performance_test(SEALContext(enc_parms))
 end
 
+
+"""
+    example_bfv_performance_custom()
+
+Show a terminal menu for selecting a custom polynomial modulus degree and use it for performance
+tests with the BFV scheme.
+
+This function is based on the file `native/examples/7_performance.cpp` of the original
+SEAL library and should yield the exact same output, except (of course) for the actual performance
+numbers.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp)
+
+See also: [`example_performance_test`](@ref), [`example_bfv_performance_default`](@ref),
+          [`bfv_performance_test`](@ref),
+          [`example_ckks_performance_custom`](@ref)
+"""
 function example_bfv_performance_custom()
   poly_modulus_degree = 0
   println()
@@ -435,6 +505,23 @@ function example_bfv_performance_custom()
   bfv_performance_test(SEALContext(enc_parms))
 end
 
+
+"""
+    example_ckks_performance_default()
+
+Perform multiple performance tests of the CKKS scheme for several polynomial modulus degrees.
+
+This function is based on the file `native/examples/7_performance.cpp` of the original
+SEAL library and should yield the exact same output, except (of course) for the actual performance
+numbers.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp)
+
+See also: [`example_performance_test`](@ref), [`example_ckks_performance_custom`](@ref),
+          [`ckks_performance_test`](@ref),
+          [`example_bfv_performance_default`](@ref)
+"""
 function example_ckks_performance_default()
   print_example_banner("CKKS Performance Test with Degrees: 4096, 8192, and 16384")
 
@@ -466,6 +553,24 @@ function example_ckks_performance_default()
   # ckks_performance_test(SEALContext(enc_parms))
 end
 
+
+"""
+    example_ckks_performance_custom()
+
+Show a terminal menu for selecting a custom polynomial modulus degree and use it for performance
+tests with the CKKS scheme.
+
+This function is based on the file `native/examples/7_performance.cpp` of the original
+SEAL library and should yield the exact same output, except (of course) for the actual performance
+numbers.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp)
+
+See also: [`example_performance_test`](@ref), [`example_ckks_performance_default`](@ref),
+          [`ckks_performance_test`](@ref),
+          [`example_bfv_performance_custom`](@ref)
+"""
 function example_ckks_performance_custom()
   poly_modulus_degree = 0
   println()
@@ -494,6 +599,24 @@ function example_ckks_performance_custom()
   ckks_performance_test(SEALContext(enc_parms))
 end
 
+
+"""
+    example_performance_test()
+
+Show a terminal menu for selecting different performance tests.
+
+This function is based on the file `native/examples/7_performance.cpp` of the original
+SEAL library and should yield the exact same output, except (of course) for the actual performance
+numbers.
+
+* [SEAL](https://github.com/microsoft/SEAL)
+* [native/examples/7_performance.cpp](https://github.com/microsoft/SEAL/blob/master/native/examples/7_performance.cpp)
+
+See also: [`example_bfv_performance_default`](@ref), [`example_bfv_performance_custom`](@ref),
+          [`bfv_performance_test`](@ref),
+          [`example_ckks_performance_default`](@ref), [`example_ckks_performance_custom`](@ref),
+          [`ckks_performance_test`](@ref)
+"""
 function example_performance_test()
   print_example_banner("Example: Performance Test")