From d8a8c797764435a03563c653a4e201df476bd68b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Tue, 10 Mar 2026 09:40:28 +0000 Subject: [PATCH] encoding: add godoc hints for cue/ast result types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For each public API that returns an ast.File or ast.Expr, give a hint to the user in terms of what they likely want to do with it. Otherwise it's difficult to guess that they need cue.Context.BuildExpr, given that it lives in a different package and is not a top-level func. While here, do very minor tweaks as well, like linkifying io.EOF. Signed-off-by: Daniel Martí Change-Id: Idf23ea15e306fc845d8e24e41a92c31e7582bbc5 Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1233277 TryBot-Result: CUEcueckoo Unity-Result: CUE porcuepine Reviewed-by: Paul Jolly --- encoding/json/json.go | 6 +++++- encoding/jsonschema/generate.go | 3 +++ encoding/jsonschema/jsonschema.go | 2 ++ encoding/openapi/decode.go | 2 ++ encoding/protobuf/protobuf.go | 4 +++- encoding/toml/decode.go | 2 ++ encoding/xml/koala/decode.go | 2 ++ encoding/yaml/yaml.go | 8 ++++++-- 8 files changed, 25 insertions(+), 4 deletions(-) diff --git a/encoding/json/json.go b/encoding/json/json.go index 97cc4d96f..edd9aa0b0 100644 --- a/encoding/json/json.go +++ b/encoding/json/json.go @@ -56,6 +56,8 @@ func Validate(b []byte, v cue.Value) error { // Extract parses JSON-encoded data to a CUE expression, using path for // position information. +// +// The result can be converted to a [cue.Value] via [cue.Context.BuildExpr]. func Extract(path string, data []byte) (ast.Expr, error) { expr, err := extract(path, data) if err != nil { @@ -114,8 +116,10 @@ type Decoder struct { readAllErr error } -// Extract converts the current JSON value to a CUE ast. It returns io.EOF +// Extract converts the current JSON value to a CUE ast. It returns [io.EOF] // if the input has been exhausted. +// +// The result can be converted to a [cue.Value] via [cue.Context.BuildExpr]. func (d *Decoder) Extract() (ast.Expr, error) { if d.readAllErr != nil { return nil, d.readAllErr diff --git a/encoding/jsonschema/generate.go b/encoding/jsonschema/generate.go index 28ba2fbff..54ac02c7b 100644 --- a/encoding/jsonschema/generate.go +++ b/encoding/jsonschema/generate.go @@ -71,6 +71,9 @@ func (m closedMode) descend() closedMode { // Generate generates a JSON Schema for the given CUE value, // with the returned AST representing the generated JSON result. +// +// The result is typically encoded as JSON, for example by obtaining a value via +// [cue.Context.BuildExpr] and then encoding it via [encoding/json.Marshal]. func Generate(v cue.Value, cfg *GenerateConfig) (ast.Expr, error) { if err := v.Validate(); err != nil { return nil, err diff --git a/encoding/jsonschema/jsonschema.go b/encoding/jsonschema/jsonschema.go index 17f4d1894..d68e621c2 100644 --- a/encoding/jsonschema/jsonschema.go +++ b/encoding/jsonschema/jsonschema.go @@ -45,6 +45,8 @@ import ( // // The generated CUE schema is guaranteed to deem valid any value that is // a valid instance of the source JSON schema. +// +// The result can be converted to a [cue.Value] via [cue.Context.BuildFile]. func Extract(data cue.InstanceOrValue, cfg *Config) (*ast.File, error) { cfg = ref(*cfg) if cfg.MapURL == nil { diff --git a/encoding/openapi/decode.go b/encoding/openapi/decode.go index 71a37ee1b..67616e882 100644 --- a/encoding/openapi/decode.go +++ b/encoding/openapi/decode.go @@ -30,6 +30,8 @@ import ( // // It currently only converts entries in #/components/schema and extracts some // meta data. +// +// The result can be converted to a [cue.Value] via [cue.Context.BuildFile]. func Extract(data cue.InstanceOrValue, c *Config) (*ast.File, error) { // TODO: find a good OpenAPI validator. Both go-openapi and kin-openapi // seem outdated. The k8s one might be good, but avoid pulling in massive diff --git a/encoding/protobuf/protobuf.go b/encoding/protobuf/protobuf.go index 7a24aa8fc..2a20da550 100644 --- a/encoding/protobuf/protobuf.go +++ b/encoding/protobuf/protobuf.go @@ -401,7 +401,9 @@ func (b *Extractor) getInst(p *protoConverter) *build.Instance { // // Extract assumes the proto file compiles with protoc and may not report an error // if it does not. Imports are resolved using the paths defined in Config. -func Extract(filename string, src interface{}, c *Config) (f *ast.File, err error) { +// +// The result can be converted to a [cue.Value] via [cue.Context.BuildFile]. +func Extract(filename string, src any, c *Config) (f *ast.File, err error) { if c == nil { c = &Config{} } diff --git a/encoding/toml/decode.go b/encoding/toml/decode.go index 45d4e0a64..609bdc45a 100644 --- a/encoding/toml/decode.go +++ b/encoding/toml/decode.go @@ -116,6 +116,8 @@ type openTableArray struct { // Decode parses the input stream as TOML and converts it to a CUE [*ast.File]. // Because TOML files only contain a single top-level expression, // subsequent calls to this method may return [io.EOF]. +// +// The result can be converted to a [cue.Value] via [cue.Context.BuildExpr]. func (d *Decoder) Decode() (ast.Expr, error) { if d.decoded { return nil, io.EOF diff --git a/encoding/xml/koala/decode.go b/encoding/xml/koala/decode.go index e26e9474f..19e4f3945 100644 --- a/encoding/xml/koala/decode.go +++ b/encoding/xml/koala/decode.go @@ -91,6 +91,8 @@ func NewDecoder(fileName string, r io.Reader) *Decoder { // Decode parses the input stream as XML and converts it to a CUE [ast.Expr]. // The input stream is taken from the [Decoder] and consumed. +// +// The result can be converted to a [cue.Value] via [cue.Context.BuildExpr]. func (dec *Decoder) Decode() (ast.Expr, error) { if dec.decoderRan { return nil, io.EOF diff --git a/encoding/yaml/yaml.go b/encoding/yaml/yaml.go index c0a5da319..f4c446aae 100644 --- a/encoding/yaml/yaml.go +++ b/encoding/yaml/yaml.go @@ -32,7 +32,9 @@ import ( // list. The src argument may be a nil, string, []byte, or io.Reader. If // src is nil, the result of reading the file specified by filename will // be used. -func Extract(filename string, src interface{}) (*ast.File, error) { +// +// The result can be converted to a [cue.Value] via [cue.Context.BuildFile]. +func Extract(filename string, src any) (*ast.File, error) { data, err := source.ReadAll(filename, src) if err != nil { return nil, err @@ -118,11 +120,13 @@ type Decoder struct { readAllErr error } -// Extract converts the current YAML value to a CUE ast. It returns io.EOF +// Extract converts the current YAML value to a CUE ast. It returns [io.EOF] // if the input has been exhausted. // // For YAML streams with multiple documents separated by `---`, each call to // Extract will return the next document as a separate CUE expression. +// +// The result can be converted to a [cue.Value] via [cue.Context.BuildExpr]. func (d *Decoder) Extract() (ast.Expr, error) { if d.readAllErr != nil { return nil, d.readAllErr -- 2.51.2