PklUnofficial

Reference

Annotations and Modifiers

Doc comments, annotations, and modifiers that shape visibility, inheritance, and tooling.

Annotations and Modifiers

Annotations and modifiers are how Pkl communicates intent to readers, tools, package documentation, and future amendments. Use them sparingly, but treat them as part of the public contract when they appear on exported declarations.

Doc Comments

Doc Comments use /// and should describe the contract rather than repeat the member name.

pkl
/// Public HTTP port for the service.port: Int(isBetween(1, 65535)) = 8080

Good doc comments explain constraints, units, defaults, and operational meaning. They are the foundation for package documentation generated by Pkldoc.

Annotations

Annotations attach structured metadata to declarations and members. Pkl tools can use that metadata for documentation, deprecation warnings, code generation, or editor affordances.

pkl
@Deprecated { message = "Use endpoint.port." }oldPort: Int = 8080

Use @Deprecated when a public member remains available but should stop being used in new modules. Keep the message actionable and point to the replacement.

Visibility Modifiers

Modifier Use
local internal helper value for the current module or object
hidden value that participates in evaluation but should not appear in rendered output
fixed member that amendments should not replace
pkl
local defaultHost = "localhost"hidden generatedLabel = "service-\(defaultHost)"fixed protocol = "https"

Use local for helper logic, hidden for implementation details that still need evaluation, and fixed when downstream amendments must not weaken a contract.

Const

const marks values intended to be constant. It is most useful for public defaults that should be safe to inline mentally.

pkl
const defaultPort = 8080

Do not use const to decorate every value. If a member is already obviously local and literal, extra modifiers can make the module harder to scan.

Class Modifiers

abstract and open shape inheritance. Use them at package boundaries where the extension story is intentional.

pkl
abstract class Storage {  name: String}open class HttpStorage extends Storage {  endpoint: String}

Prefer closed contracts by default. Add extension points only when downstream packages are meant to build on them.

Public Contract Checklist

  • Exported classes and type aliases have doc comments.
  • Deprecated members name their replacement.
  • Helpers are local before they become visible API by accident.
  • Render-only internals are hidden.
  • Non-overridable defaults are fixed.
  • Extension modifiers are reserved for real package API design.