What is the recommended docstring format?

Questions
1

Hi,

Is there a specific/recommended docstring format for Typst?

2

Hello @Llama,

You can take a look at the following:

I am unsure how up-to-date the docs are, but that’s the “recommended” syntax, as in, the one tinymist supports.

P.S.: I have changed your topic’s title to match the guidelines at How to post in the Questions category. Don’t hesitate to read it!

1 Like
3

Hi @Llama

I want to add that this syntax for documenting function parameters

/// - x (int): The input of the function `f`.
#let f(x, y) = { /* code */ };

as currently still listed in the Tinymist docs is more and more being replaced by

/// Function description ...
#let f(
  // The input of the function `f`.
  // -> int
  x, 

  y
) = { /* code */ };

This new syntax is implemented since tidy:0.4.0 and is the widely pretty much approved result of extensive discussion with the Typst community. The old syntax is the initial design introduced by early versions of Tidy but has some disadvantages compared to the new one:

  • In the old syntax the parameter name needs to be repeated which is an easy source of errors when the parameter names are changed.
  • A “magic” parameter list (i.e., special structure) was needed in the function doc-comment.
  • With the new syntax, readability is improved greatly.

Note also that the -> type annotation syntax is temporary because there are no built-in type annotations in Typst yet (but they are planned!).

2 Likes
4

Hi @Llama, don’t forget to tick one of the responses if you got a satisfying answer. The answer you choose should usually be the response that you found most correct/helpful/comprehensive for the question you asked.