docs: registry

internal/registry/registry.go

@@ -1,3 +1,5 @@
+// Package registry defines a structure to hold all available representations,
+// engines, and conversions between them.
 package registry
 
 import (
@@ -6,12 +8,15 @@ import (
 	"maps"
 )
 
+// A Registry holds all representations, conversions, codecs, and engines
+// available to the program.
 type Registry struct {
 	codecs    map[string]Codec
 	converter *Converter
 	engines   map[string]Engine
 }
 
+// New makes an empty registry.
 func New() *Registry {
 	return &Registry{
 		codecs:    map[string]Codec{},
@@ -20,6 +25,8 @@ func New() *Registry {
 	}
 }
 
+// GetEngine finds an engine based on its name. Returns an error if an engine
+// with that name cannot be found.
 func (r Registry) GetEngine(name string) (Engine, error) {
 	e, ok := r.engines[name]
 	if !ok {
@@ -29,10 +36,13 @@ func (r Registry) GetEngine(name string) (Engine, error) {
 	return e, nil
 }
 
+// ListEngines returns all available engines to the registry.
 func (r Registry) ListEngines() iter.Seq[Engine] {
 	return maps.Values(r.engines)
 }
 
+// GetDefaultEngine infers the preferred engine for a representation. Returns an
+// error if one cannot be chosen.
 func (r *Registry) GetDefaultEngine(id string) (Engine, error) {
 	for _, engine := range r.engines {
 		if engine.InType() == id {
@@ -45,6 +55,12 @@ func (r *Registry) GetDefaultEngine(id string) (Engine, error) {
 	// return nil, fmt.Errorf("no engine for '%s'", id)
 }
 
+// ConvertTo attempts to convert an expression of one type of representation to
+// another. Returns the converted expression, otherwise an error.
+//
+// It can convert between any two types of representations, given there is a
+// valid conversion path between them. It uses BFS to traverse a graph of
+// conversion edges, and converts along the shortest path.
 func (r *Registry) ConvertTo(expr Expr, outType string) (Expr, error) {
 	path, err := r.ConversionPath(expr.Repr(), outType)
 	if err != nil {
@@ -62,6 +78,8 @@ func (r *Registry) ConvertTo(expr Expr, outType string) (Expr, error) {
 	return result, err
 }
 
+// Marshal serializes an expression, given that representation has a codec.
+// Returns an error if the representation is not registered, or it has no codec.
 func (r *Registry) Marshal(expr Expr) (string, error) {
 	m, ok := r.codecs[expr.Repr()]
 	if !ok {
@@ -71,6 +89,8 @@ func (r *Registry) Marshal(expr Expr) (string, error) {
 	return m.Encode(expr)
 }
 
+// Unmarshal deserializes an expression. Returns an error if the representation
+// or a codec for it is not registered.
 func (r *Registry) Unmarshal(s string, outType string) (Expr, error) {
 	m, ok := r.codecs[outType]
 	if !ok {
@@ -94,6 +114,9 @@ func reverse[T any](list []T) []T {
 	return reversed
 }
 
+// ConversionPath attempts to find a set of valid conversions that (if applied)
+// convert one representation to another. Returns an error if no path can be
+// found.
 func (r *Registry) ConversionPath(from, to string) ([]Conversion, error) {
 	backtrack := map[string]Conversion{}
 	iteration := []string{from}