Preserving comments on pkl eval #215

New Issue

adam · 2025-12-30T01:22:19+01:00

adam commented

2025-12-30 01:22:19 +01:00

Originally created by @jjuliano on GitHub (Oct 15, 2024).

I have a PKL template configuration file, and I'd like to ensure that comments are preserved after pkl eval, as the output is the user-facing configuration file. Is there a way to retain the comments in the generated document on pkl eval?

Originally created by @jjuliano on GitHub (Oct 15, 2024). I have a PKL template configuration file, and I'd like to ensure that comments are preserved after pkl eval, as the output is the user-facing configuration file. Is there a way to retain the comments in the generated document on pkl eval?

adam commented

2025-12-30 01:22:20 +01:00

@odenix commented on GitHub (Oct 16, 2024):

As far as I know, this isn’t currently possible.

How would you like comments to be propagated from the Pkl template to the (YAML?) output?
Should this only happen for top-level properties to avoid duplicated comments?

@odenix commented on GitHub (Oct 16, 2024): As far as I know, this isn’t currently possible. How would you like comments to be propagated from the Pkl template to the (YAML?) output? Should this only happen for top-level properties to avoid duplicated comments?

adam commented

2025-12-30 01:22:20 +01:00

@jjuliano commented on GitHub (Oct 16, 2024):

I think similar to how dynamic objects are not supported in other template format. The process can also strip comments on selected output.

@jjuliano commented on GitHub (Oct 16, 2024): I think similar to how dynamic objects are not supported in other template format. The process can also strip comments on selected output.

adam commented

2025-12-30 01:22:20 +01:00

@StefMa commented on GitHub (Oct 16, 2024):

What if you modify an output with an custom Renderer? 🤔
Where should the comment than be placed?
I guess it is nearly impossible to say because you actually don't know what the new output will be...

@StefMa commented on GitHub (Oct 16, 2024): What if you modify an output with an custom `Renderer`? 🤔 Where should the comment than be placed? I guess it is nearly impossible to say because you actually don't know what the new output will be...

adam commented

2025-12-30 01:22:20 +01:00

@bioball commented on GitHub (Oct 17, 2024):

Something that you can do quite easily is to add top-level comments to a document, like so:

output {
  text = """
    // This is a rendered file! DO NOT EDIT
    \(super.text)
    """
}

But it's much less trivial if you want comments interspersed throughout the rendered file; most comments (line comments and block comments) are treated as whitespace and thrown away.

However, doc comments can be obtained through reflection:

/// Here are my doc comments
module myModule

import "pkl:reflect"

local mod = reflect.Module(module)

myDocComments = mod.docComment

This produces:

myDocComments = "Here are my doc comments"

Our code generators for Swift and Go are written in Pkl, and use reflection to obtain these doc comments, which then get rendered as comments in the target language. E.g.

18676a5e87/codegen/src/internal/ClassGen.pkl (L186-L188)

44a04408df/codegen/src/internal/ClassGen.pkl (L144-L147)

@bioball commented on GitHub (Oct 17, 2024): Something that you can do quite easily is to add top-level comments to a document, like so: ```pkl output { text = """ // This is a rendered file! DO NOT EDIT \(super.text) """ } ``` But it's much less trivial if you want comments interspersed throughout the rendered file; most comments (line comments and block comments) are treated as whitespace and thrown away. However, doc comments can be obtained through reflection: ```pkl /// Here are my doc comments module myModule import "pkl:reflect" local mod = reflect.Module(module) myDocComments = mod.docComment ``` This produces: ``` myDocComments = "Here are my doc comments" ``` Our code generators for Swift and Go are written in Pkl, and use reflection to obtain these doc comments, which then get rendered as comments in the target language. E.g. https://github.com/apple/pkl-go/blob/18676a5e876c90600b8058ffb489fa8148e7869d/codegen/src/internal/ClassGen.pkl#L186-L188 https://github.com/apple/pkl-swift/blob/44a04408df3ecffde883900e0df905950fe9db0c/codegen/src/internal/ClassGen.pkl#L144-L147

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/pkl#215