Annotations on function parameters #299

New Issue

adam · 2025-12-30T01:23:16+01:00

adam commented

2025-12-30 01:23:16 +01:00

Originally created by @emdemir on GitHub (Mar 12, 2025).

Problem Definition

I'd like to expose metadata on function parameters through reflection, which can later be used for things like code generators. An example could be defining HTTP APIs using abstract functions which could look like this:

@http.GET
@http.Path("/{name}")
abstract function getUserInfo(@http.FromPath name: String): UserInfo

I tried to see if there are other approaches such as defining this in constraints, but those aren't accessible through pkl:reflect.

Solution

Make it possible to add annotations to function parameters.

Alternatives

Add the annotation to the function itself with something like @http.FromPath("location"). Makes it repetitive and moves the annotation away from its target.
Make the function arguments a class and define the annotations on properties. It becomes much more verbose to define things.

Originally created by @emdemir on GitHub (Mar 12, 2025). # Problem Definition I'd like to expose metadata on function parameters through reflection, which can later be used for things like code generators. An example could be defining HTTP APIs using `abstract function`s which could look like this: ```pkl @http.GET @http.Path("/{name}") abstract function getUserInfo(@http.FromPath name: String): UserInfo ``` I tried to see if there are other approaches such as defining this in constraints, but those aren't accessible through `pkl:reflect`. # Solution Make it possible to add annotations to function parameters. # Alternatives - Add the annotation to the function itself with something like `@http.FromPath("location")`. Makes it repetitive and moves the annotation away from its target. - Make the function arguments a class and define the annotations on properties. It becomes much more verbose to define things.

adam closed this issue

2025-12-30 01:23:16 +01:00

adam commented

2025-12-30 01:23:17 +01:00

@HT154 commented on GitHub (Mar 12, 2025):

Using a class here actually seems idiomatic to me as a means of declaratively defining inputs and outputs. Functions in Pkl are limited (intentionally). It's actually common to use classes as functions, so much so that there's a named pattern for doing so: Class-as-a-function. I get that it's a good deal more verbose, but I'd argue that's a good thing: in this example it seems like you'd want to be able to add a doc comment to each parameter explaining its purpose/functionality.

@HT154 commented on GitHub (Mar 12, 2025): Using a class here actually seems idiomatic to me as a means of declaratively defining inputs and outputs. Functions in Pkl are limited (intentionally). It's actually common to use classes as functions, so much so that there's a named pattern for doing so: [Class-as-a-function](https://pkl-lang.org/blog/class-as-a-function.html). I get that it's a good deal more verbose, but I'd argue that's a good thing: in this example it seems like you'd want to be able to add a doc comment to each parameter explaining its purpose/functionality.

adam commented

2025-12-30 01:23:18 +01:00

@emdemir commented on GitHub (Mar 12, 2025):

I see. And you have guessed correctly that being able to add documentation to parameters was my next problem. Then we will stick with a pattern similar to Class-as-a-function for the input. Thanks!

@emdemir commented on GitHub (Mar 12, 2025): I see. And you have guessed correctly that being able to add documentation to parameters was my next problem. Then we will stick with a pattern similar to Class-as-a-function for the input. Thanks!

adam referenced this issue

2025-12-30 01:24:57 +01:00

[PR #299] [MERGED] Fix missing closing quotes in Local dependencies part of language-reference doc #495

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/pkl#299