feat: fill argument descriptions from JSDoc @param and Python Args:
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-tscollects the leading comments, and for the entrypointfunctionreads the@paramlines of its last/** */block:@param name text,@param {type} name - textand@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'sotyp, the same field Python uses. AT | T[]union keeps its marker instead.inferArgs(frontend/src/lib/infer.ts), the server'smain_arg_schema(windmill-parser/src/json_schema.rs, used when a script is deployed without a schema) and the CLI'sgenerate-metadata(cli/src/utils/metadata.ts) set the property'sdescriptionfrom a non-unionotyp, forpython3,deno,bun,bunnativeandnativetsonly. Other languages useotypfor 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 timeswith the text going on to the next line: the two lines are joined.@param ghost ...names no parameter ofmain: ignored.loudhas no@param: no description.- After Deploy, the script's run form shows the descriptions, so they are saved in the schema.
- Adding a
@paramline 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 onmain(left: [None, None, Some("string | string[]"), None]).rustfmt --checkon the two Rust files andprettier --checkoninfer.ts: pass.oxlintoninfer.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-tsreads@paramlines from the entrypoint function's JSDoc block and passes each description as the argument'sotyp, matching howwindmill-parser-pyhandlesArgs:. Multi-line descriptions are joined; ones containing both[and|are dropped since they would collide with theT | T[]union marker.@paramlines 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-sidemain_arg_schema, and the CLI'sinferSchemaset the property'sdescriptionfrom a non-unionotypforpython3,deno,bun,bunnative, andnativets. 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-tspackage (1.695.0), so the TypeScript half needs a new release of that package; the Python half needs none.