LYR-SEM0225

a module without module documentation

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

A module that declares something pub does not begin with //! lines. Not said unless the lint is set to warn.

Explanation

//! lines at the top of a file document the module: the editor shows them over the module's path, lyric doc makes the module's page of them. The lint is allow by default.

Say what the module is for in //! lines at the top of the file.

Wrong

//- lyric.toml
[package]
name = "app"
version = "0.1.0"

[lints]
warn = ["missing-module-docs"]
//- src/shapes.lyr
/// The area of a rectangle `w` wide and `h` high.
pub fn area(w: int, h: int): int {
    return w * h;
}
//- src/main.lyr
import app.shapes;

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

Right

//- lyric.toml
[package]
name = "app"
version = "0.1.0"

[lints]
warn = ["missing-module-docs"]
//- src/shapes.lyr
//! Areas of shapes.

/// The area of a rectangle `w` wide and `h` high.
pub fn area(w: int, h: int): int {
    return w * h;
}
//- src/main.lyr
import app.shapes;

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