Update documentation for kyaml package

kyaml/kio/byteio_reader.go

@@ -19,7 +19,7 @@ const (
 	ResourceListApiVersion = "kyaml.kustomize.dev/v1alpha1"
 )
 
-// ByteReadWriter reads from an input and writes to an output
+// ByteReadWriter reads from an input and writes to an output.
 type ByteReadWriter struct {
 	// Reader is where ResourceNodes are decoded from.
 	Reader io.Reader

kyaml/kio/doc.go

@@ -0,0 +1,32 @@
+// Package kio contains libraries for reading and writing collections of Resources.
+//
+// Reading Resources
+//
+// Resources are Read using a kio.Reader function.  Examples:
+//  [kio.LocalPackageReader{}, kio.ByteReader{}]
+//
+// Resources read using a LocalPackageReader will have annotations applied so they can be
+// written back to the files they were read from.
+//
+// Modifying Resources
+//
+// Resources are modified using a kio.Filter.  The kio.Filter accepts a collection of
+// Resources as input, and returns a new collection as output.
+// It is recommended to use the yaml package for manipulating individual Resources in
+// the collection.
+//
+// Writing Resources
+//
+// Resources are Read using a kio.Reader function.  Examples:
+//  [kio.LocalPackageWriter{}, kio.ByteWriter{}]
+//
+// ReadWriters
+//
+// It is preferred to use a ReadWriter when reading and writing from / to the same source.
+//
+// Building Pipelines
+//
+// The preferred way to transforms a collection of Resources is to use kio.Pipeline to Read,
+// Modify and Write the collection of Resources.  Pipeline will automatically sequentially
+// invoke the Read, Modify, Write steps, returning and error immediately on any failure.
+package kio

kyaml/kio/kio.go

@@ -30,22 +30,23 @@ type Writer interface {
 	Write([]*yaml.RNode) error
 }
 
+// WriterFunc implements a Writer as a function.
 type WriterFunc func([]*yaml.RNode) error
 
 func (fn WriterFunc) Write(o []*yaml.RNode) error {
 	return fn(o)
 }
 
-// GrepFilter modifies a collection of Resource Configuration by returning the modified slice.
+// Filter modifies a collection of Resource Configuration by returning the modified slice.
 // When possible, Filters should be serializable to yaml so that they can be described
-// declaratively as data.
+// as either data or code.
 //
 // Analogous to http://www.linfo.org/filters.html
 type Filter interface {
 	Filter([]*yaml.RNode) ([]*yaml.RNode, error)
 }
 
-// FilterFunc can be used to implement GrepFilter by defining a function.
+// FilterFunc implements a Filter as a function.
 type FilterFunc func([]*yaml.RNode) ([]*yaml.RNode, error)
 
 func (fn FilterFunc) Filter(o []*yaml.RNode) ([]*yaml.RNode, error) {
@@ -53,7 +54,7 @@ func (fn FilterFunc) Filter(o []*yaml.RNode) ([]*yaml.RNode, error) {
 }
 
 // Pipeline reads Resource Configuration from a set of Inputs, applies some
-// transformations, and writes the results to a set of Outputs.
+// transformation filters, and writes the results to a set of Outputs.
 //
 // Analogous to http://www.linfo.org/pipes.html
 type Pipeline struct {
@@ -69,7 +70,8 @@ type Pipeline struct {
 	Outputs []Writer `yaml:"outputs,omitempty"`
 }
 
-// Execute implements the Pipeline pipeline.
+// Execute executes each step in the sequence, returning immediately after encountering
+// any error as part of the Pipeline.
 func (p Pipeline) Execute() error {
 	var result []*yaml.RNode
 

kyaml/kio/pkgio_reader.go

@@ -17,6 +17,7 @@ import (
 // files.
 var requiredResourcePackageAnnotations = []string{kioutil.IndexAnnotation, kioutil.PathAnnotation}
 
+// PackageBuffer implements Reader and Writer, storing Resources in a local field.
 type PackageBuffer struct {
 	Nodes []*yaml.RNode
 }
@@ -30,6 +31,9 @@ func (r *PackageBuffer) Write(nodes []*yaml.RNode) error {
 	return nil
 }
 
+// LocalPackageReadWriter reads and writes Resources from / to a local directory.
+// When writing, LocalPackageReadWriter will delete files if all of the Resources from
+// that file have been removed from the output.
 type LocalPackageReadWriter struct {
 	Kind string `yaml:"kind,omitempty"`
 

kyaml/kio/tree.go

@@ -27,7 +27,7 @@ const (
 	TreeStructureGraph TreeStructure = "graph"
 )
 
-// TreeWriter prints the package structured as a tree
+// TreeWriter prints the package structured as a tree.
 // TODO(pwittrock): test this package better.  it is lower-risk since it is only
 // used for printing rather than updating or editing.
 type TreeWriter struct {