Tidy:0.4.0 - A new documentation syntax

Showcase
, ,
1

Package-time!

This release is a major redesign of the documentation syntax, intending to pave the way for eventual built-in documentation support. There is a migration guide for adopting the new syntax.

Instead of (old)

/// This function computes the cardinal sine, $sinc(x)=sin(x)/x$. 
///
/// - x (int, float): The argument for the cardinal sine function. 
/// -> float
#let sinc(x) = if x == 0 {1} else {calc.sin(x) / x}

we now write (new)

/// This function computes the cardinal sine, $sinc(x)=sin(x)/x$. 
///
/// -> float
#let sinc(
  /// The argument for the cardinal sine function. 
  /// -> int | float
  x
) = if x == 0 {1} else {calc.sin(x) / x}

The new style

  • removes almost all extra syntax and makes use of pure Typst syntax (cross references are now handled via single @ instead of @@).
  • moves the parameter descriptions right in front of each parameter.
  • has a temporary syntax for type annotations that makes it relatively easy to switch to the built-in solution that we are expecting to have soon in Typst.

The old syntax

Note that you can also keep using the old syntax which will still be around for some time. It can be activated via tidy.show-module(old-syntax: true, ...).

New features

  • New parser for the new documentation syntax. The old parser is still available and can be activated via tidy.show-module(old-syntax: true).
  • Cross-references to function arguments.
  • Support for detecting curried functions, i.e., function aliases with prepended arguments using the .with() function.
  • Auto-previewed examples can now be written with (inspired by the official Typst documentation)
    ```example
#rect()
```
    or
    ```examplec
rect()
```

Iā€™m happy to get feedback. Enjoy!

8 Likes