Preserving comments on pkl eval

[jjuliano]

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?

[translatenix]

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?

[jjuliano]

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

[StefMa]

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...

[bioball]

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.

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