LYR-SEM0223

a pub declaration without documentation

warning · spec 01-lexical · lint missing-docs, group docs, allow unless said

A pub function, type, field, method or module binding has no /// above it; a method a conformance answers is documented by its interface. Not said unless the lint is set to warn.

Explanation

What a package makes pub is what its users read about in lyric doc and in their editor; without a /// they read only the signature. The lint is allow by default; a library sets it to deny in its [lints].

Say what it is in a /// above it.

Wrong

@Warn("missing-docs")
pub fn area(w: int, h: int): int {
    return w * h;
}

fn main(): void {
    let _ = area(2, 3);
}

Right

/// The area of a rectangle `w` wide and `h` high.
@Warn("missing-docs")
pub fn area(w: int, h: int): int {
    return w * h;
}

fn main(): void {
    let _ = area(2, 3);
}