feat: fill argument descriptions from JSDoc @param and Python Args:

Merged
BU
1d ago
+197-18

What does this PR do?

A TypeScript script can document its inputs with JSDoc @param lines on main, and a Python script with a docstring Args: section. Neither text reached the inferred schema, so the editor's form and the deployed script's run form showed no descriptions.

The Python parser already reads Args: and passes each description as the argument's otyp (#7400, kept by #12473), but nothing turned otyp into a schema description: inferArgs only reads otyp for the T | T[] marker.

This PR does two things:

  • windmill-parser-ts collects the leading comments, and for the entrypoint function reads the @param lines of its last /** */ block: @param name text, @param {type} name - text and @param [name=default] text. A description carries on over the following lines until a blank line or another tag. Each one goes to the argument's otyp, the same field Python uses. A T | T[] union keeps its marker instead.
  • inferArgs (frontend/src/lib/infer.ts), the server's main_arg_schema (windmill-parser/src/json_schema.rs, used when a script is deployed without a schema) and the CLI's generate-metadata (cli/src/utils/metadata.ts) set the property's description from a non-union otyp, for python3, deno, bun, bunnative and nativets only. Other languages use otyp for a type name.

Code fills, it never overwrites: a description written in code (a Python docstring Args: entry or a TS JSDoc @param) is used only when the argument has no description yet, as with a new script, a new argument, or one left empty. A description already in the schema, typed in the editor or saved earlier, is always kept, and an empty doc entry changes nothing. The server deploy path, wmill generate-metadata and the editor apply the same rule. The editor re-infers while you type, so a description it filled from the doc earlier in the session keeps following the doc text until you type your own. Once saved, a later change to the doc text does not update the description; clear the description to pick it up again.

Size: windmill-parser-ts/src/lib.rs +38 / -3, json_schema.rs +73 / -10 (tests included), windmill-api-scripts/src/scripts.rs +6 / -1, infer.ts +16 / -2, cli/src/utils/metadata.ts +11 / -2, tests in windmill-parser-ts/tests/tests.rs (+35) and cli/test/generate_metadata_unit.test.ts (+18).

flowchart LR
    A[JSDoc @param / Python Args:] --> B[parser: description in otyp]
    B -->|Before| C[inferArgs ignores it: form shows no description]
    B -->|After| D[inferArgs sets description: editor and run form show it]

Narrated recording, before then after (sound on):

https://github.com/user-attachments/assets/768160fb-a416-41bd-8d78-1505c2c75e96

The recording is the real app: the frontend dev server from this checkout, against the main backend image (CE v1.875.0). The scripts were created through the API before recording. Waits on page loads are shortened; nothing else is edited.

The editor runs the published windmill-parser-wasm-ts package (1.695.0), so the TypeScript half needs a new release of that package. For the "after" part I built the parser crate to wasm from this branch (windmill-parser-wasm with --features ts-parser, then wasm-bindgen --target web) and put it in node_modules. The "before" part runs main with the published package. The Python part needs no new package: the published windmill-parser-wasm-py already returns the Args: text.

Edge cases and unchanged behaviour checked

In the running app, on this branch:

  • @param {string} name - Who to greet: the type and the dash are dropped.
  • @param [times=1] How many times with the text going on to the next line: the two lines are joined.
  • @param ghost ... names no parameter of main: ignored.
  • loud has no @param: no description.
  • After Deploy, the script's run form shows the descriptions, so they are saved in the schema.
  • Adding a @param line while editing: the form picks it up.
  • Python Args: (city: ..., days (int): ...): both descriptions now show.
  • Unchanged: a TypeScript script without JSDoc keeps the description typed in the schema editor.

Not covered: destructured parameters (the parser names them anon1, ...), const main = () => {} (the parser reads only function main), and the CLI's generate-metadata and the backend's json_schema.rs (they don't read otyp either). A description that contains both [ and | is taken for the T | T[] marker, as it already is for Python.

Checks run

  • cargo test -p windmill-parser-ts: 36 passed. The new test fails on main (left: [None, None, Some("string | string[]"), None]).
  • rustfmt --check on the two Rust files and prettier --check on infer.ts: pass. oxlint on infer.ts: no findings.
  • cargo clippy -p windmill-parser-ts: no warnings on the changed lines.

Related issue

Part of #2451 (the TypeScript half; the Python parser half was #12473). The CLI's generate-metadata is not wired up here.

AI tools (Claude Code) assisted with this change; the behaviour was verified as shown.


Summary by cubic

Makes TypeScript JSDoc @param descriptions and Python docstring Args: text appear in the editor's form, the deploy-time schema, and the CLI's generate-metadata. Previously both parsers surfaced the text but nothing turned it into an argument description.

  • windmill-parser-ts reads @param lines from the entrypoint function's JSDoc block and passes each description as the argument's otyp, matching how windmill-parser-py handles Args:. Multi-line descriptions are joined; ones containing both [ and | are dropped since they would collide with the T | T[] union marker. @param lines for parameters that don't exist are ignored, and the parser skips comment collection on the job path since no schema is built there.
  • inferArgs, the server-side main_arg_schema, and the CLI's inferSchema set the property's description from a non-union otyp for python3, deno, bun, bunnative, and nativets. A code description only fills an empty one, never replacing a description typed in the schema editor; an empty doc entry also keeps a typed description.

Migration

  • The editor runs the published windmill-parser-wasm-ts package (1.695.0), so the TypeScript half needs a new release of that package; the Python half needs none.