nordisk/Skidbladnir

tests/doc_placement.rs

//! **A doc comment sits on the function it documents (stinky #25).**
//!
//! Two blocks had slid onto the wrong item. `install_systemd_scoped`'s docs sat on
//! top of `enclosing_cargo_target_dir`, which left the install with no docs and made
//! rustdoc open the target-dir probe with "Privileged/per-user install". The same
//! happened to `mark_binary_executable`'s note, which ended up heading
//! `write_file_with_mode`.

/// The `///` block directly above `signature` (attributes skipped), one line each.
fn doc_above(src: &str, signature: &str) -> Vec<String> {
    let lines: Vec<&str> = src.lines().collect();
    let at = lines
        .iter()
        .position(|l| l.starts_with(signature))
        .unwrap_or_else(|| panic!("no `{signature}` in the source"));
    let mut doc = Vec::new();
    for l in lines[..at].iter().rev() {
        let t = l.trim_start();
        if t.starts_with("#[") {
            continue;
        }
        match t.strip_prefix("///") {
            Some(d) => doc.push(d.trim().to_string()),
            None => break,
        }
    }
    doc.reverse();
    doc
}

#[test]
fn each_doc_comment_sits_on_the_function_it_describes() {
    let systemd = include_str!("../crates/skidbladnir-systemd/src/systemd.rs");
    let install = include_str!("../src/install.rs");
    let cases = [
        (systemd, "pub fn install_systemd_scoped(spec: &SystemdServiceSpec, scope: Scope)", "Privileged/per-user install"),
        (systemd, "pub fn enclosing_cargo_target_dir(", "Is `path` inside a cargo target directory?"),
        (install, "fn write_file_with_mode(", "Write one rendered file"),
        (install, "fn mark_binary_executable(", "entrypoint"),
    ];
    let mut bad = Vec::new();
    for (src, sig, first) in cases {
        let doc = doc_above(src, sig);
        match doc.first() {
            Some(l) if l.contains(first) => {}
            other => bad.push(format!("`{sig}`: doc opens with {other:?}, expected `{first}`")),
        }
        let stray = doc.iter().skip(1).filter(|l| l.starts_with("**") || l.starts_with("Privileged")).count();
        if stray > 0 {
            bad.push(format!("`{sig}`: a second item's doc is glued into this one: {doc:#?}"));
        }
    }
    assert!(bad.is_empty(), "{}", bad.join("\n"));
}