Documentation comments

Document your code and browse docs with valk doc.

On this page

A /// block directly above a declaration documents it. Editors show it on hover, and valk doc prints it in the terminal or turns it into a reference.

Write a doc comment#

The text is markdown. The first paragraph is the summary; everything after it is the full description:

Valk

/// Splits `text` at each `sep` and returns the parts.
///
/// Empty parts are kept:
///
/// ```valk
/// split_all("a,,b", ",") // "a", "", "b"
/// ```
+ fn split_all(text: String, sep: String) Array[String] {
    return text.split(sep)
}

/// How many requests the server handled so far.
+ global requests: uint (0)

/// A user account.
+ class User {
    /// Shown on the profile page.
    + name: String
}

fn main() {}

Functions, classes, properties, globals, enums, error types and aliases can all have one. A plain // comment is not documentation.

Mark a function deprecated#

Add the $deprecated flag and say what to use instead. Calls from other packages get a warning that quotes the sentence starting with "Deprecated"; --no-warn-deprecated silences it:

Valk

/// Deprecated: use `split_all` instead.
+ fn split_old(text: String) Array[String] $deprecated {
    return text.split(",")
}

fn main() {}

Look something up#

Name a declaration to read its docs in the terminal:

Terminal

valk doc http.Server.compress   # standard library
valk doc Array.sort             # core types need no namespace
valk doc ./my-package Client    # a declaration in a package

Generate a reference#

Point valk doc at a project directory to document all its namespaces:

Terminal

valk doc . -o docs/api.md --markdown --no-private
valk doc . -o docs/api.md --markdown --full   # whole blocks, not just summaries
valk doc . -o api.json                        # JSON, for tools

Option	Effect
`--markdown`	Markdown instead of JSON
`-o path`	Write to a file
`--full`	Print the whole doc block under each signature, not only the summary
`--no-private`	Leave out declarations that are not public

Build options such as --def and --target work here too, so code behind #if is documented for that build.

View page source ↗