encoding: adopt naming convention for conversions

Change-Id: I626753fdc2a8b8ffb03d3a64ec5514f7cb6d06bf
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/2440
Reviewed-by: Marcel van Lohuizen <[email protected]>

Author: mpvl

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