encoding: adopt naming convention for conversions
Change-Id: I626753fdc2a8b8ffb03d3a64ec5514f7cb6d06bf
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/2440
Reviewed-by: Marcel van Lohuizen <mpvl@golang.org>
diff --git a/encoding/doc.go b/encoding/doc.go
index 12c3a28..c3cd793 100644
--- a/encoding/doc.go
+++ b/encoding/doc.go
@@ -14,4 +14,23 @@
// Package encoding contains subpackages to convert CUE to and from byte-level
// and textual representations.
+//
+// For some packages, CUE can be mapped to both concrete values and higher-level
+// definitions. For instance, a Go value can be mapped based on its concrete
+// values or on its underlying type. Similarly, the protobuf package can extract
+// CUE definitions from .proto definitions files, but also convert proto
+// messages to concrete values.
+//
+// To clarify between these cases, we adopt the following naming convention:
+//
+// Name Direction Level Example
+// Decode x -> CUE Value Convert an incoming proto message to CUE
+// Encode CUE -> x Value Convert CUE to JSON
+// Extract x -> CUE Type Extract CUE definition from .proto file
+// Generate CUE -> x Type Generate OpenAPI definition from CUE
+//
+// To be more precise, Decoders and Encoders deal with concrete values only.
+//
+// Unmarshal and Marshal are used if the respective Decoder and Encoder decode
+// and encode from and to a stream of bytes.
package encoding
