refactor: clean comments and docstring

crates/sesam-vitale/src/cps.rs

@@ -2,13 +2,6 @@ use libc::{c_void, size_t};
 use std::ffi::CString;
 use std::ptr;
 
-/*
-1. CB = Caractères Binaires »
-2. CE = Caractères « Etendus » (ISO 8859-1)
-3. CA = Caractères Alphanumériques (ASCII?)
-4. CN = Caractères Numériques
-*/
-
 use crate::libssv::SSV_LireCartePS;
 use crate::ssv_memory::{decode_ssv_memory, Block};
 
@@ -18,6 +11,10 @@ pub struct CartePS {
     situations: Vec<SituationPS>,
 }
 
+// 1. CB = Caractères Binaires »
+// 2. CE = Caractères « Etendus » (ISO 8859-1)
+// 3. CA = Caractères Alphanumériques (ASCII?)
+// 4. CN = Caractères Numériques
 #[derive(Debug, Default)]
 struct TitulairePS {
     type_de_carte_ps: String,                         // CN
@@ -261,20 +258,21 @@ mod test_decode_carte_ps {
     #[test]
     fn test_francoise_pharmacien0052419() {
         let bytes: &[u8] = &[
-            0, 1, 51, // 3
+            0, 1, 51, // Block 01, Content size 51
-            1, 48, // 2
+            1, 48, // Field 01, Content size 1
-            1, 56, // 2
+            1, 56, // Field 02, Content size 1
-            11, 57, 57, 55, 48, 48, 53, 50, 52, 49, 57, 52, // 12
+            11, 57, 57, 55, 48, 48, 53, 50, 52, 49, 57, 52, // Field 03, Content size 11
-            1, 52, // 2
+            1, 52, // Field 04, Content size 1
-            2, 50, 50, // 3
+            2, 50, 50, // Field 05, Content size 2
-            17, 80, 72, 65, 82, 77, 65, 67, 73, 69, 78, 48, 48, 53, 50, 52, 49, 57, // 18
+            17, 80, 72, 65, 82, 77, 65, 67, 73, 69, 78, 48, 48, 53, 50, 52, 49,
-            9, 70, 82, 65, 78, 67, 79, 73, 83, 69, // 10
+            57, // Field 06, Content size 17
-            1, 84, // 2
+            9, 70, 82, 65, 78, 67, 79, 73, 83, 69, // Field 07, Content size 9
-            // total: 54
+            1, 84, // Field 08, Content size 1
-            0, 2, 83, 1, 1, 1, 48, 1, 49, 2, 56, 54, 1, 49, 9, 48, 66, 48, 50, 50, 49, 57, 53, 56,
+            0, 2, 83, // Block 02, Content size 83
-            1, 56, 24, 80, 72, 65, 82, 77, 65, 67, 73, 69, 32, 68, 85, 32, 67, 69, 78, 84, 82, 69,
+            1, 1, 1, 48, 1, 49, 2, 56, 54, 1, 49, 9, 48, 66, 48, 50, 50, 49, 57, 53, 56, 1, 56, 24,
-            50, 50, 49, 57, 53, 8, 48, 48, 50, 48, 50, 52, 49, 57, 1, 56, 0, 1, 48, 1, 49, 2, 53,
+            80, 72, 65, 82, 77, 65, 67, 73, 69, 32, 68, 85, 32, 67, 69, 78, 84, 82, 69, 50, 50, 49,
-            48, 2, 49, 48, 2, 48, 48, 1, 48, 1, 48, 1, 48, 1, 49, 1, 49,
+            57, 53, 8, 48, 48, 50, 48, 50, 52, 49, 57, 1, 56, 0, 1, 48, 1, 49, 2, 53, 48, 2, 49,
+            48, 2, 48, 48, 1, 48, 1, 48, 1, 48, 1, 49, 1, 49,
         ];
         let blocks = decode_ssv_memory(bytes, bytes.len());
         let carte_ps = decode_carte_ps(blocks);

crates/sesam-vitale/src/libssv.rs

@@ -1,9 +1,7 @@
-/**
+/// libssv.rs
- * libssv.rs
+///
- *
+/// Low level bindings to the SSVLIB dynamic library.
- * Low level bindings to the SSVLIB dynamic library.
+// TODO : look for creating a dedicated *-sys crate : https://kornel.ski/rust-sys-crate
- * TODO : look for creating a dedicated *-sys crate : https://kornel.ski/rust-sys-crate
- */
 use libc::{c_char, c_ushort, c_void, size_t};
 
 #[cfg_attr(target_os = "linux", link(name = "ssvlux64"))]
@@ -22,4 +20,4 @@ extern "C" {
         TTailleDonneesSortie: *mut size_t,
     ) -> c_ushort;
 }
-/* TODO : replace void* by Rust struct : https://doc.rust-lang.org/nomicon/ffi.html#representing-opaque-structs */
+// TODO : replace void* by Rust struct : https://doc.rust-lang.org/nomicon/ffi.html#representing-opaque-structs

crates/sesam-vitale/src/main.rs

@@ -5,5 +5,4 @@ mod ssvlib_demo;
 
 fn main() {
     ssvlib_demo::demo();
-    // XXX
 }

crates/sesam-vitale/src/ssv_memory.rs

@@ -1,30 +1,27 @@
 /// # SSV Memory
 /// Provide functions to manipulate raw memory from SSV library.
-/// 
-
 use std::convert::TryFrom;
 
-// TODO : Est-ce qu'on pourrait/devrait définir un type custom pour représenter les tableaux de bytes ?
-
 #[derive(PartialEq, Debug)]
 struct ElementSize {
     pub size: usize,
     pub pad: usize,
 }
 
+// TODO : Est-ce qu'on pourrait/devrait définir un type custom pour représenter les tableaux de bytes ?
+
 impl TryFrom<&[u8]> for ElementSize {
     type Error = &'static str;
 
     fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
-        /* Longueur:
-         *   - si le bit de poids fort du premier octet est à 0, la longueur est codée sur un octet
-         *   - si le bit de poids fort du premier octet est à 1, les 7 bits de poids faible codent le nombre d'octets utilisés pour coder la longueur
-         */
         if bytes.is_empty() {
             return Err("Empty bytes input");
         }
 
         let mut element_size = ElementSize { size: 0, pad: 1 };
+        // Longueur:
+        //   - si le bit de poids fort du premier octet est à 0, la longueur est codée sur un octet
+        //   - si le bit de poids fort du premier octet est à 1, les 7 bits de poids faible codent le nombre d'octets utilisés pour coder la longueur
         if bytes[0] & 0b1000_0000 == 0 {
             // Size coded on 1 byte
             element_size.size = bytes[0] as usize;

crates/sesam-vitale/src/ssvlib_demo.rs

@@ -1,16 +1,11 @@
+/// High level API for the SSV library,
+/// based on the low level bindings in libssv.rs.
 extern crate dotenv;
 use libc::{c_void, size_t};
-/**
- * High level API for the SSV library,
- * based on the low level bindings in libssv.rs.
- *
- */
-use std::path::PathBuf;
-
-use std::ffi::CString;
-use std::ptr;
-
 use std::env;
+use std::ffi::CString;
+use std::path::PathBuf;
+use std::ptr;
 
 use crate::cps::lire_carte;
 use crate::libssv::{SSV_InitLIB2, SSV_LireConfig};
@@ -44,17 +39,16 @@ fn ssv_lire_config() {
 }
 
 pub fn demo() {
-    /*
+    // TODO : this is probably not working on release, because I'm not sure it exists a CARGO_MANIFEST_DIR and so it can find the `.env`
-     * TODO : this is probably not working on release, because I'm not sure it exists a CARGO_MANIFEST_DIR and so it can find the `.env`
+    // Maybe we could use a system standard config path to store a config file
-     * Maybe we could use a system standard config path to store a config file
-     */
     let manifest_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
     let manifest_path = PathBuf::from(manifest_dir);
     dotenv::from_path(manifest_path.join(".env")).ok();
 
-    println!("------- Demo for the SSV library 2 --------");
+    println!("------- Demo for the SSV library --------");
 
     ssv_init_lib_2();
+
     let code_pin = "1234";
     let lecteur = "HID Global OMNIKEY 3x21 Smart Card Reader 0";
     let carte_ps = lire_carte(code_pin, lecteur);