How to document variadic arguments

[johannes-wolf]

Thank you for this project!

In CeTZ we use a lot of var-args my-fun(..options), but I could find no way to
get typst-doc to match the argument to my docstring line:

//// my-fun
/// - ..options (any): Text

does not work. Is this currently possible?

[Mc-Zen]

Hi @johannes-wolf ,
Yes, I also came across this with quill and it is already fixed but not pushed yet!

/// - ..options (any): Text

is (will be) the correct way.

I am currently working on the interface for allowing ouput style customization and this delayed the update.

[Mc-Zen]

By the way, I've already seen the current documentation of CeTZ (amazing work you have done there) some weeks ago and it features a lot of visual examples. Can I invite you to a discussion about (hopefully) supporting that in function descriptions?

#4

[johannes-wolf]

By the way, I've already seen the current documentation of CeTZ (amazing work you have done there) some weeks ago and it features a lot of visual examples. Can I invite you to a discussion about (hopefully) supporting that in function descriptions?

#4

Yes :). I was also thinking about support for examples. My idea was to support custom tags/blocks that one can register callbacks for. When rendering these tags/blocks, the callback is called to return content.
Something like

/// Function
/// - my-arg (int): Text
///   :example:
///   Here comes some raw text that is passed to a callback.
///   :end-example:

[Mc-Zen]

Oh sorry, the #4 was intended to be the link for the disussion and I explained the current status there but anyway :D

This is a great idea!

[Mc-Zen]

Hi @johannes-wolf,
Could the cases that you have in mind be equally elegantly solved by passing a set of objects that will be added to the scope? What I mean:

// mymodule.typ

/// Function
/// - my-arg (int): Text
/// #example1
#let my-function(my-arg) = {}

// documentation.typ

#let example1 = [
   // this may call anything, even #image() and #import()
}
#parse-module(read("mymodule.typ"), scope: (example1: example1))

Or would the custom blocks and tags suggested by you add extra benefit or elegance? Because we could also have it both in that case.

[johannes-wolf]

I think the version your example uses is fine. 👍
Would like to have code for smaller examples directly in the comment, which should work that way.

[Mc-Zen]

alright, thanks for your feedback :)

[Mc-Zen]

Hi @johannes-wolf ,
This package has just been officially released under the new name tidy.

You can now pass arbitrary variables to the docstring parser and they will be available in every docstring. The nice thing is that this even works with modules. For your project this would go along the lines of

#{
  import "@preview/cetz:0.0.2"
  let the-module = parse-module(read("cetz.draw"), scope: (cetz: cetz))
  show-module(the-module)
}

It would be even be feasible (and surely worth) writing a function that displays and executes example code (avoiding the duplication). A rough idea for that:

#let example(code, prepend: "") = {
  table(columns: (1fr, 1fr),
   raw(code.text, block: true, lang: "typc"),
   eval(prepend + "\n" + code.text, mode: "code", scope: (cetz: cetz))
  )
}

It forwards the cetz module into the (nested) eval'ed code and shows as well as executes the example code. Of course example() also needs to be added to the scope dictionary.

The docstring can now call it like this:

///
/// #example(`circle((0,0), name: "circle")`, prepend: "import cetz.draw: *")
///

or something similar.

Documenting variadic arguments is possible now as well ;)

Have fun!