LYR-SEM0224

a doc link that names nothing

warning · spec 01-lexical · lint broken-doc-link, group docs, warn unless said

A /// links [Name] or [Type.member], and nothing of that name is visible where the documented declaration stands.

Explanation

In a ///, [Name] and [Type.member] link to the declaration they name; lyric doc makes them links, the editor follows them. One that names nothing — a typo, a declaration renamed or removed — leads nowhere. Text in backticks or in a code fence is not read, nor is a Markdown link [text](url).

Name a type, a function or a member the module sees, or write the text in backticks.

Wrong

/// Twice `x`; [halve] goes the other way.
fn twice(x: int): int {
    return x * 2;
}

fn main(): void {
    let _ = twice(1);
}

Right

/// Half of `x`.
fn halve(x: int): int {
    return x / 2;
}

/// Twice `x`; [halve] goes the other way.
fn twice(x: int): int {
    return x * 2;
}

fn main(): void {
    let _ = twice(halve(4));
}