Code Documentation

Tinymist will read the documentation from the source code and display it in the editor. For example, you can hover over a identifier to see its documentation, usually the content of the comments above the identifier's definition. The format of the documentation follows this guideline.

Note: the feature is not yet officially supported.

• ✓ Syntax of Docstring's Content: We have reached consensus on the syntax of content. It MUST be written in Typst.

• ? Annotations in Docstring's Content: We check the annotations in docstring by tidy style (< v0.4.0). It's not an official standard.

  • Related Issue: Tidy #53: Long-term compatibility with tinymisttinymist.
• ✗ Syntax of Docstring: We haven't reached consensus on the syntax of docstring. It's not clear whether we should distinguish the docstring from regular comments.

A docstring is an object in source code associating with some typst definition, whose content is the documentation information of the definition. Documentation is placed on consecutive special comments using three forward slashes ////// and an optional space. These are called doc comments.

While the DocCommentMatcherDocCommentMatcher matches doc comments in a looser way, we recommend using the strict syntax mentioned in the following sections.

The content MUST follow typst syntax instead of markdown syntax.

/// You can use *typst markup* in docstring.

#let foo = 1;

/// You can use *typst markup* in docstring.

#let foo = 1;

/// You can use *typst markup* in docstring.

#let foo = 1;

/// You can use *typst markup* in docstring.

#let foo = 1;

Explanation: The documentation of foofoo is "You can use typst markup in docstring."

The comments SHOULD be line comments starting with three forward slashes ////// and an optional space.

/* I'm a regular comment */

#let foo = 1;

// I'm a regular comment.

#let foo = 1;

//// I'm a regular comment.

#let foo = 1;

/* I'm a regular comment */

#let foo = 1;

// I'm a regular comment.

#let foo = 1;

//// I'm a regular comment.

#let foo = 1;

/* I'm a regular comment */

#let foo = 1;

// I'm a regular comment.

#let foo = 1;

//// I'm a regular comment.

#let foo = 1;

/* I'm a regular comment */

#let foo = 1;

// I'm a regular comment.

#let foo = 1;

//// I'm a regular comment.

#let foo = 1;

Explanation: There SHOULD be no documentation for foofoo in the three cases. The first comment is not a line comment, the second and the third one don't start with exact three forward slashes. However, the language server will regard them as doc comments loosely.

The comments SHOULD be consecutively and exactly placed aside the associating definition.

/// 1

/// 2

#let foo = 1;

/// 1

/// 2

#let foo = 1;

/// 1

/// 2

#let foo = 1;

/// 1

/// 2

#let foo = 1;

Explanation: The documentation of foofoo is "1\\n2""1\\n2".

/// 1

/// 2

#let bar = 1;

/// 1

/// 2

#let bar = 1;

/// 1

/// 2

#let bar = 1;

/// 1

/// 2

#let bar = 1;

Explanation: The documentation of barbar is "2""2", because there is a space between /// 1/// 1 and /// 2/// 2.

/// 1

/// 2

#let baz = 1;

/// 1

/// 2

#let baz = 1;

/// 1

/// 2

#let baz = 1;

/// 1

/// 2

#let baz = 1;

Explanation: There SHOULD be no documentation for bazbaz, because the comments is not exactly placed before the let statement of the bazbaz.

A module-level appears at the beginning of the module (file).

Given a file foo.typfoo.typ containing code:

/// 1

/// 2

#let baz = 1;

/// 1

/// 2

#let baz = 1;

/// 1

/// 2

#let baz = 1;

/// 1

/// 2

#let baz = 1;

Explanation: The documentation of the module foofoo (foo.typfoo.typ) is "1""1". It is not "1\n2""1\n2", because there is a space between /// 1/// 1 and /// 2/// 2.

Given a file foo.typfoo.typ containing code:

// License: Apache 2.0

/// 1

// License: Apache 2.0

/// 1

// License: Apache 2.0

/// 1

// License: Apache 2.0

/// 1

Explanation: The documentation of the module foofoo (foo.typfoo.typ) is "1""1". It is not "License: Apache 2.0\n1""License: Apache 2.0\n1", because // License: Apache 2.0// License: Apache 2.0 is not a strict doc comment.

A variable appears exactly before some let statement (the ast starting with #let#let or letlet). BNF Syntax:

VAR_DOCSTRING_CONTENT ::= MARKUP { VAR_SUB_ANNOATATION } [ VAR_INIT_ANNOATATION ]

VAR_DOCSTRING_CONTENT ::= MARKUP { VAR_SUB_ANNOATATION } [ VAR_INIT_ANNOATATION ]

VAR_DOCSTRING_CONTENT ::= MARKUP { VAR_SUB_ANNOATATION } [ VAR_INIT_ANNOATATION ]

VAR_DOCSTRING_CONTENT ::= MARKUP { VAR_SUB_ANNOATATION } [ VAR_INIT_ANNOATATION ]

You can use an arrow ->-> following a type annotation to mark the type of the initializer expression of the let statement. The initializer expression is the expression at the right side of the equal marker in the let statement. BNF Syntax:

VAR_INIT_ANNOATATION ::= '-> ' TYPE_ANNOATATION

VAR_INIT_ANNOATATION ::= '-> ' TYPE_ANNOATATION

VAR_INIT_ANNOATATION ::= '-> ' TYPE_ANNOATATION

VAR_INIT_ANNOATATION ::= '-> ' TYPE_ANNOATATION

/// -> int

#let f(x) = { /* code */ };

/// -> int

#let f(x) = { /* code */ };

/// -> int

#let f(x) = { /* code */ };

/// -> int

#let f(x) = { /* code */ };

Explanation: The docstring tells that the type of { /* code */ }{ /* code */ } is intint. Thus, the resultant type of the function ff is also annotated as intint.

/// -> float

#let G = { /* code */ };

/// -> float

#let G = { /* code */ };

/// -> float

#let G = { /* code */ };

/// -> float

#let G = { /* code */ };

Explanation: The docstring tells that the type of { /* code */ }{ /* code */ } is floatfloat. Thus, the type of the variable GG is also annotated as floatfloat.

You can use a list item - name (type): description- name (type): description to document the related variable at the left side of the let statement. BNF Syntax:

VAR_SUB_ANNOATATION ::= '- ' NAME '(' TYPE_ANNOATATION ')' ':' MARKUP

VAR_SUB_ANNOATATION ::= '- ' NAME '(' TYPE_ANNOATATION ')' ':' MARKUP

VAR_SUB_ANNOATATION ::= '- ' NAME '(' TYPE_ANNOATATION ')' ':' MARKUP

VAR_SUB_ANNOATATION ::= '- ' NAME '(' TYPE_ANNOATATION ')' ':' MARKUP

/// - x (int): The input of the function `f`.

#let f(x, y) = { /* code */ };

/// - x (int): The input of the function `f`.

#let f(x, y) = { /* code */ };

/// - x (int): The input of the function `f`.

#let f(x, y) = { /* code */ };

/// - x (int): The input of the function `f`.

#let f(x, y) = { /* code */ };

Explanation: The docstring tells that the type of xx is intint and the documentation of xx is "The input of the function ff."

/// - x (any): The swapped value from `y`.

#let (x, y) = (y, x);

/// - x (any): The swapped value from `y`.

#let (x, y) = (y, x);

/// - x (any): The swapped value from `y`.

#let (x, y) = (y, x);

/// - x (any): The swapped value from `y`.

#let (x, y) = (y, x);

Explanation: The docstring tells that the type of xx at the left side is anyany and its documentation is "The swapped value from yy." The variables at the right side of the let statement are not documented by the docstring.

You can use #example#example function to provide examples in docstrings.

#example(`

$ sum f(x) = 10 $

`)

#example(`

$ sum f(x) = 10 $

`)

#example(`

$ sum f(x) = 10 $

`)

#example(`

$ sum f(x) = 10 $

`)

The docstring tells that there is an associated example in the docstring. It will be rendered as a code block following the rendered result when possible:

$ sum f(x) = 10 $

$ sum f(x) = 10 $

$ sum f(x) = 10 $

$ sum f(x) = 10 $

A type annotation is a comma separated list containing types. BNF Syntax:

TYPE_ANNOATATION ::= TYPE { ',' TYPE }

TYPE_ANNOATATION ::= TYPE { ',' TYPE }

TYPE_ANNOATATION ::= TYPE { ',' TYPE }

TYPE_ANNOATATION ::= TYPE { ',' TYPE }

Currently, only built-in types and the generic array type are supported in docstrings.

The list of built-in types:

• anyany
• contentcontent
• nonenone
• autoauto
• boolbool or booleanboolean
• falsefalse
• truetrue
• intint or integerinteger
• floatfloat
• lengthlength
• angleangle
• ratioratio
• relativerelative
• fractionfraction
• strstr or stringstring
• colorcolor
• gradientgradient
• patternpattern
• symbolsymbol
• versionversion
• bytesbytes
• labellabel
• datetimedatetime
• durationduration
• stylesstyles
• arrayarray
• dictionarydictionary
• functionfunction
• argumentsarguments
• typetype
• modulemodule
• pluginplugin