PBS autocomplete parameter names for stdlib and method calls
This commit is contained in:
+31
-12
@@ -2,7 +2,7 @@
|
||||
id: AGD-0040
|
||||
ticket: pbs-autocomplete-parameter-names
|
||||
title: PBS autocomplete parameter names for stdlib and method calls
|
||||
status: open
|
||||
status: accepted
|
||||
created: 2026-05-08
|
||||
resolved:
|
||||
decision:
|
||||
@@ -46,15 +46,21 @@ This agenda is narrower than `DSC-0036`.
|
||||
|
||||
## 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?
|
||||
- [x] Should canonical parameter names be owned by the compiler semantic callable model, or is stdlib/API metadata allowed to remain a separate source of truth?
|
||||
- Answer: canonical parameter names should be offered through the compiler semantic model.
|
||||
- [x] Is `arg0`/`arg1` allowed to reach any user-facing LSP/editor surface, or must it be treated as an internal fallback only?
|
||||
- Answer: `arg0`/`arg1` should not reach user-facing editor or LSP surfaces.
|
||||
- [x] For the first implementation slice, should the decision cover all callable symbols or explicitly target stdlib/host-backed APIs first?
|
||||
- Answer: the decision should cover all callable symbols.
|
||||
- [x] Are parameter names part of the normative public API contract for stdlib and host-backed surfaces?
|
||||
- Answer: parameter names should be treated as part of the normative public API contract.
|
||||
|
||||
Non-blocking implementation investigations:
|
||||
|
||||
- Determine how stdlib APIs are represented today: PBS declarations, Java/Kotlin host descriptors, compiler intrinsics, generated metadata, or a mix.
|
||||
- Verify whether user-authored PBS functions already preserve source parameter names through the compiler-backed LSP path.
|
||||
- Decide exact snippet formatting after the canonical parameter source is settled.
|
||||
- Defer optional/default/rest parameter representation until PBS has that callable shape.
|
||||
|
||||
## Options
|
||||
|
||||
@@ -134,6 +140,13 @@ The real question is ownership:
|
||||
- does the editor receive them as structured data?
|
||||
- can tests assert that stdlib APIs do not leak fallback names?
|
||||
|
||||
Questions that do not need to block the decision:
|
||||
|
||||
- The current storage shape of stdlib declarations is implementation discovery; it affects the plan, but not the ownership decision.
|
||||
- User-authored function behavior should be verified, but the target contract can still require every callable symbol to expose the same parameter shape eventually.
|
||||
- Snippet placeholder details belong in plan/spec once the canonical parameter identity is decided.
|
||||
- Optional/default/rest parameters are future callable-shape concerns unless current PBS or stdlib APIs already expose them.
|
||||
|
||||
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:
|
||||
@@ -146,8 +159,14 @@ Potential acceptance examples for a later decision/plan:
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
Proposed resolution:
|
||||
|
||||
- canonical parameter names are owned by the compiler semantic callable model;
|
||||
- stdlib, host-backed, builtin, and user-authored callables should all expose parameter names through the same semantic callable shape;
|
||||
- generated fallback names such as `arg0` and `arg1` are internal only and must not appear in completion, signature help, hover, or other user-facing editor/LSP surfaces;
|
||||
- parameter names for stdlib and host-backed APIs are normative public API surface, so renaming them should be treated as an API compatibility concern;
|
||||
- implementation may still be staged, but the normative decision should cover all callable symbols rather than defining a stdlib-only contract.
|
||||
|
||||
## 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.
|
||||
If this resolution matches the intended direction, the next step is to accept the agenda and create a decision artifact from it.
|
||||
|
||||
Reference in New Issue
Block a user