New documentation format

[Mc-Zen]

This issue tracks the progress on a major update to the documentation syntax.

Many of these decisions were discussed here typst-community/guidelines#8 and on Discord.

Overview

• Update how descriptions are read. Requires a new doc-comment parser.
• Replace @@ syntax with normal @ references.
• Use special raw elements for examples.

This will also bring the documentation style very close to the current Typst documentation (although that is still written in Rust, as of now). Also, on a sidenote, the Typst documentation does not quite use Typst markup at the moment, but rather markdown (e.g., section headings are written as #, not = and cross-references use markdown link syntax).

In my personal opinion, it is a nice and suitable philosophy to write Typst documentation in valid Typst. The new update targets this philosophy.

Descriptions

In comparison to before, the parameters descriptions are now stripped off the main function description and placed right before each parameter.

/// Description
/// -> float
#let my-function(

  /// Parameter x.
  /// -> float
  x: 999,

  /// Parameter y.
  /// -> int | float
  x: 420,
) = {}

For more information, see #33 .

As long as we don't have type annotations ...

Before Typst features built-in type annotations, a temporary syntax is introduced. The description of a definition or parameter can end with a type annotation starting with -> followed by a list of possible types separated by the pipe | operator.

I anticipate that moving documentation towards built-in type annotations will then be easy - maybe automatable - for sorce code written in this style.

References

Due to internal reasons, in the early days of Tidy, the decision was made to introduce a custom syntax for cross-references using a double @@ symbol.

@tingerrr has pointed out, that it would also be possible to just use Typst referencing syntax, i.e., a single @. This could internally be realized via a show rule that displays a link to the respective entry.

Proposal:

• Cross-references to other functions or variables are written as @my-other-definition.
• Cross-references to a specific parameter of another function are written as @my-func.x.

Both should result in valid Typst markup in all cases.

For more information, see #34 .

Code examples

Every good documentation needs some examples. Typst-package-authors like them to be displayed automatically along with the rendered output. For this, Tidy provides the example function which is available in all doc-comments. Inspired by the Typst documentation, it's rather straight-forward to allow for using regular raw syntax in combination with a special "language". This can be simply implemented with a show rule.

/// My function
///
/// ```example
/// #my-func(12)
/// ```
#let my-func(x)

For more information, see #35 .

[Myriad-Dreamin]

imo we shouldn't remove old doc comment parser to ensure compatibility. The suitable timing to remove them might be the day when we have type annotations.

[Myriad-Dreamin]

besides, it looks like the new syntax isn't friendly to documenting a function or let bindiing destructing the parameters in place. e.g.

#let f(((((x,),y),z),w),s) = x+y+z+w+s;

we'll have a bad reformatted result on above function if we use the new syntax.

[Mc-Zen]

imo we shouldn't remove old doc comment parser to ensure compatibility. The suitable timing to remove them might be the day when we have type annotations.

Both parsers will live side-by-side for a while. You can specify which one you want to use.

[Mc-Zen]

besides, it looks like the new syntax isn't friendly to documenting a function or let bindiing destructing the parameters in place. e.g.

#let f(((((x,),y),z),w),s) = x+y+z+w+s;

we'll have a bad reformatted result on above function if we use the new syntax.

True, but nor could the older parser handle destructured parameters.

Not quite sure if one should even have something like that in a public API function. Do you have a use-case in mind that couldn't be written in anther way?

I'd vote to just write a single parameter in your proposed case, say that it takes an array and properly document how the argument should look like.

[Mc-Zen]

Actually, what you can do with the new parser (and couldn't with the old one) is at least

/// Description
#let func(
  /// The argument. 
  ((c,),d)
  )

which gives