const DECLARATIONS: &[&str] = &[
"pub struct ",
"pub fn ",
"pub const fn ",
"fn init(",
"fn fmt(",
"fn source(",
"fn default(",
"fn process_aad_bytes(",
"fn process_bytes(",
"fn do_final(",
"fn mac(",
"fn reset(",
"fn update_output_len(",
"fn output_len(",
"fn underlying_cipher(",
"fn key(",
"fn nonce(",
"fn mac_size(",
"fn initial_aad(",
];
fn missing_timing_docs(source: &str) -> (usize, Vec<String>) {
let mut docs = String::new();
let mut attribute_depth = 0_i32;
let mut checked = 0;
let mut missing = Vec::new();
for line in source.lines().map(str::trim) {
if line == "#[cfg(test)]" {
break;
}
if let Some(comment) = line.strip_prefix("///") {
docs.push_str(comment);
docs.push('\n');
continue;
}
if line.starts_with("#[") || attribute_depth > 0 {
attribute_depth += line.chars().filter(|&c| c == '[').count() as i32;
attribute_depth -= line.chars().filter(|&c| c == ']').count() as i32;
continue;
}
if line.is_empty() || line.starts_with("//") {
continue;
}
if DECLARATIONS.iter().any(|prefix| line.starts_with(prefix)) {
checked += 1;
let docs = docs.to_ascii_lowercase();
if docs.contains("constant time") == docs.contains("variable time") {
missing.push(line.to_owned());
}
}
docs.clear();
}
(checked, missing)
}
#[test]
fn the_scanner_requires_exactly_one_timing_classification_on_each_declaration() {
let fixture = "\
/// Constant time.
pub struct Documented {}
pub struct Undocumented {}
/// VARIABLE TIME.
#[inline]
pub fn accepted() {}
/// Constant time and variable time.
fn init() {}
fn do_final() {}
/// Constant time when the cipher's is.
fn process_bytes() {}
fn reset() {}
impl Trait for Type {
fn drop() {}
}
#[cfg(test)]
mod tests {
fn mac() {}
}
";
let (checked, missing) = missing_timing_docs(fixture);
assert_eq!(checked, 7);
assert_eq!(
missing,
[
"pub struct Undocumented {}",
"fn init() {}",
"fn do_final() {}",
"fn reset() {}",
]
);
}
#[test]
fn every_public_api_and_implemented_trait_method_has_an_unambiguous_timing_doc() {
let mut report = Vec::new();
for (name, source) in [
("ccm/engine.rs", include_str!("../src/ccm/engine.rs")),
("eax/engine.rs", include_str!("../src/eax/engine.rs")),
(
"errors/aead_error.rs",
include_str!("../src/errors/aead_error.rs"),
),
(
"errors/aead_init_error.rs",
include_str!("../src/errors/aead_init_error.rs"),
),
("gcm/engine.rs", include_str!("../src/gcm/engine.rs")),
(
"gcm_siv/engine.rs",
include_str!("../src/gcm_siv/engine.rs"),
),
("kccm/engine.rs", include_str!("../src/kccm/engine.rs")),
("ocb/engine.rs", include_str!("../src/ocb/engine.rs")),
(
"params/aead_params_owned.rs",
include_str!("../src/params/aead_params_owned.rs"),
),
(
"params/aead_params_ref.rs",
include_str!("../src/params/aead_params_ref.rs"),
),
(
"params/params_with_aead_owned.rs",
include_str!("../src/params/params_with_aead_owned.rs"),
),
(
"params/params_with_aead_ref.rs",
include_str!("../src/params/params_with_aead_ref.rs"),
),
(
"traits/initial_aad.rs",
include_str!("../src/traits/initial_aad.rs"),
),
(
"traits/mac_size.rs",
include_str!("../src/traits/mac_size.rs"),
),
("traits/nonce.rs", include_str!("../src/traits/nonce.rs")),
] {
let (checked, missing) = missing_timing_docs(source);
if checked == 0 {
report.push(format!("{name}: no declarations scanned"));
}
for line in missing {
report.push(format!("{name}: {line}"));
}
}
assert!(
report.is_empty(),
"missing timing docs:\n{}",
report.join("\n")
);
}