prometeu-studio/discussion/workflow/agendas/AGD-0040-pbs-autocomplete-parameter-names-for-stdlib-and-method-calls.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0040	pbs-autocomplete-parameter-names	PBS autocomplete parameter names for stdlib and method calls	open	2026-05-08			compiler-pbs studio lsp autocomplete signature-help stdlib

Pain

Domain owner: compiler/pbs

Autocomplete and signature help currently show method/function parameters as arg0, arg1, etc., especially for stdlib APIs, making calls hard to understand at the point of use.

The immediate user-facing problem is not just cosmetic. When a completion inserts or previews something like:

• draw(arg0, arg1, arg2)
• setTile(arg0, arg1, arg2)
• loadSprite(arg0)

the editor fails at the exact moment it should reduce lookup cost. The user has to leave the call site, inspect docs/source, or guess what each argument means.

For PBS, this is especially damaging because stdlib and host-backed APIs are likely to be the most frequently discovered through autocomplete.

Context

The compiler-backed LSP wave can surface completions, hover, and signature help, but the parameter identity exposed to editor consumers is not yet reliable or authored enough for ergonomic API use.

Subdomains touched:

• compiler/general
• studio/lsp
• tools/vscode-extension

Related discussions:

• DSC-0035 established the compiler-backed editor assistance wave.
• DSC-0036 is discussing authored symbol documentation and markdown hover.

This agenda is narrower than DSC-0036.

DSC-0036 asks how symbol documentation should be authored and transported. This agenda asks where canonical parameter names come from and how completion/signature surfaces should consume them. Parameter names may later connect to documentation, but they need their own canonical identity even without full prose documentation.

Open Questions

• Where should canonical parameter names for stdlib and builtins live?
• Should parameter names be part of the compiler semantic model, external stdlib metadata, authored documentation, or derived from declarations?
• How should completion snippets, signature help, and hover consume the same parameter identity?
• Should generated fallback names like arg0 be allowed to reach user-facing editor UI at all?
• Do user-authored PBS functions already preserve parameter names well enough, or is the problem shared by all callable symbols?
• Are stdlib APIs represented as PBS declarations, Java/Kotlin host descriptors, compiler intrinsics, generated metadata, or a mix?
• Should parameter names be normative API surface, meaning renames require compatibility/release discipline?
• How should optional/default/rest parameters be represented if PBS supports or later adds them?
• Should completion snippets include placeholders named from canonical parameters, or should names appear only in detail/signature help?

Options

Option A - Canonical parameter names live in the compiler semantic callable model

• Approach: every callable symbol resolved by the compiler has an explicit parameter list with stable names, types, order, and origin. LSP completion, signature help, and hover all read from that same semantic shape.
• Pro: one authoritative contract; works for user code, stdlib, builtins, and host-backed APIs if they are projected into the semantic model.
• Con: requires stdlib/builtin surfaces to provide or be lowered into real parameter metadata instead of ad hoc editor-only labels.
• Maintainability: strong. It makes arg0 a compiler/model quality issue rather than a UI formatting problem.

Option B - Parameter names live in stdlib/API metadata consumed by the LSP adapter

• Approach: stdlib and host-backed APIs carry external metadata for names and docs; LSP consumes that metadata when building completion items and signatures.
• Pro: fast path for the worst current pain if the main offender is stdlib; avoids forcing every host descriptor into a richer compiler model immediately.
• Con: risks splitting callable truth between compiler semantics and editor metadata. User-authored and stdlib callables may drift.
• Maintainability: medium. Acceptable as a migration step, but weak as the final owner if the compiler and editor can disagree.

Option C - Derive display names in the editor/LSP when semantic names are missing

• Approach: keep existing compiler output and have LSP/VS Code replace arg0, arg1 with guessed names from docs, method names, types, or curated maps.
• Pro: minimal compiler change; can improve a handful of visible APIs quickly.
• Con: guessing parameter names is fragile and can mislead users. It treats presentation as truth.
• Maintainability: weak. This should be reserved only as a temporary compatibility shim with clear diagnostics.

Option D - Bind parameter names to the documentation model from DSC-0036

• Approach: parameter names and descriptions are authored together in the symbol documentation surface, then completion/signature help extract display names from docs.
• Pro: ties names and descriptions together; can produce rich signature help.
• Con: parameter identity becomes dependent on documentation authoring. A callable without docs could still degrade to arg0.
• Maintainability: medium-to-weak as a canonical source. Good for prose descriptions, poor for structural identity.

Option E - Allow arg0/arg1 internally but ban them from user-facing LSP output

• Approach: define a conformance rule: generated fallback parameter names may exist internally, but completion/signature/hover must either show canonical names or omit placeholder names instead of exposing argN.
• Pro: creates a clear UX quality gate and prevents the worst editor output.
• Con: does not by itself solve where real names come from.
• Maintainability: strong as a guardrail, incomplete as the main design.

Tradeoffs

The central tradeoff is speed versus ownership.

An editor-only fix can make the UI look better quickly, but it creates a second source of truth for API shape. That is exactly the kind of split that becomes expensive once hover, snippets, signature help, diagnostics, docs, and future refactors all need the same callable metadata.

Putting names into the compiler semantic model is heavier, but it matches the long-term direction implied by compiler-backed editor assistance. The editor should not need to know why a callable is user-authored, stdlib, host-backed, or intrinsic in order to display a usable signature.

There is still room for a staged path:

• immediately block or reduce argN in user-facing output;
• add canonical names for stdlib APIs through the nearest existing stdlib descriptor;
• converge those descriptors into the compiler's callable semantic model;
• let documentation add descriptions, examples, and prose later without owning structural names.

DSC-0036 should remain complementary. Documentation can describe what a parameter means, but the parameter name itself should be structural metadata.

Recommendation

Use Option A as the target design and Option E as a non-negotiable editor quality guardrail.

Recommended direction:

1. Treat canonical parameter names as part of the resolved callable symbol model.
2. Require stdlib, builtin, host-backed, and user-authored callables to expose the same parameter shape to editor assistance.
3. Define arg0, arg1, etc. as internal fallback names only; they should not appear in completion labels, snippets, signature help, or hover unless explicitly authored as real API names.
4. Let the documentation model from DSC-0036 attach parameter descriptions later, but not replace structural parameter identity.

If implementation needs to be staged, the first slice should target the stdlib because that is where the current UX pain is most visible.

Discussion

This agenda should avoid reducing the problem to "prettier snippets".

The real question is ownership:

• who owns a callable's parameter names?
• does the compiler know them?
• does the editor receive them as structured data?
• can tests assert that stdlib APIs do not leak fallback names?

The minimum acceptable outcome is that a user can discover a stdlib call from autocomplete and understand what each argument is supposed to represent without leaving the call site.

Potential acceptance examples for a later decision/plan:

• completion insert text uses named placeholders where snippets are enabled;
• signature help displays stable parameter names and types;
• hover can show a callable signature using the same names;
• conformance tests fail if public stdlib callables expose argN placeholders;
• fallback behavior is explicit when a callable genuinely lacks parameter names.

Resolution

Ainda em aberto.

Next Step

Discutir se a equipe aceita compiler/pbs como owner dos nomes canonicos de parametros e se argN deve ser banido de qualquer surface LSP user-facing.