Merge pull request #669 from vmware-tanzu/document-pkgs

Add documentation for all packages

pkg/cmd/doc.go

@@ -0,0 +1,16 @@
+// Copyright 2022 VMware, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package cmd is home to the full set of ytt's "commands" -- instances of cobra.Command
+(not to be confused with ./cmd which contains the bootstrapping for executing ytt in various environments).
+
+A cobra.Command is the starting point of execution.
+
+For a list of commands run:
+
+   $ ytt help
+
+The default command is "template".
+*/
+package cmd

pkg/cmd/template/cmd.go

@@ -15,9 +15,10 @@ import (
 	"github.com/vmware-tanzu/carvel-ytt/pkg/yamlmeta"
 )
 
-// Options both holds all settings for and implements the "template" command.
+// Options both contains the configuration for a "template" command AND the
+// top-level implementation of that command.
 //
-// For proper initialization, always use NewOptions().
+// For most intents and purposes, RunWithFiles() is the entrypoint.
 type Options struct {
 	IgnoreUnknownComments   bool
 	ImplicitMapKeyOverrides bool

pkg/cmd/template/doc.go

@@ -0,0 +1,12 @@
+// Copyright 2022 VMware, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package template implements the "template" command (not to be confused with
+"pkg/template" home of the templating mechanism itself).
+
+Front-and-center is template.Options. This is both the host of ytt settings
+parsed from the command-line through Cobra AND the top-level logic that
+implements the command.
+*/
+package template

pkg/cmd/ui/doc.go

@@ -0,0 +1,8 @@
+// Copyright 2022 VMware, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package ui provides a thin abstraction over user input and output (typically,
+a tty device).
+*/
+package ui

pkg/doc.go

@@ -0,0 +1,239 @@
+// Copyright 2022 VMware, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package pkg is the collection of packages that make up the implementation of ytt.
+
+This codebase is intentionally organized into well-defined layers. A concerted
+effort has been sustained to keep the responsibility of each package concise and
+complete. Packages have been designed to be dependent on each other only to the
+degree absolutely required.
+
+In the inventory, below, individual packages are named alongside their coupling
+with the other packages in the codebase.
+
+    (# of dependents) => <package name> => (# of dependencies)
+
+Where "# of dependents" is the count of packages that import the named package
+and "# of dependencies" is the count of packages that this named package
+imports.
+
+This is output from the tool https://github.com/jtigger/go-orient.
+
+From top-down (http://www.catb.org/~esr/writings/taoup/html/ch04s03.html), ytt
+code is layered in this way:
+
+Entry Point
+
+ytt is built into two executable formats:
+
+    ./cmd/ytt                  // a command-line tool
+    ./cmd/ytt-lambda-website   // an AWS Lambda function
+
+ytt's contains a mini website that is the "Playground".
+
+    (1) => pkg/website => (0)
+
+Commands
+
+There are half-a-dozen commands ytt implements. The most commonly used and most
+complex is "template".
+
+    (1) => pkg/cmd => (8)
+    (2) => pkg/cmd/template => (10)
+
+The Workspace
+
+ytt processing can be thought of as a sequence of steps: schema "pre-processing",
+data values "pre-processing", template evaluation, and overlay "post-processing".
+All of these steps are executed over a collection of files we call a
+workspace.Library.
+
+    (1) => pkg/workspace => (14)
+    (2) => pkg/workspace/datavalues => (6)
+    (3) => pkg/workspace/ref => (2)
+    (4) => pkg/files => (1)
+    (10) => pkg/filepos => (0)
+
+Templating
+
+The heart of ytt's action is structural templating. There are two flavors of
+templates: templating on a YAML structure and templating on text. Each source
+template file is "compiled" into a Starlark program whose job is to build-up
+the output.
+
+    (9) => pkg/template => (2)
+    (9) => pkg/template/core => (1)
+    (3) => pkg/yamltemplate => (6)
+    (2) => pkg/texttemplate => (2)
+
+Standard Library
+
+ytt injects a collection of "standard" modules into Starlark executions.
+These modules support serialization, hashing, parsing of special kinds
+of values, and programmatic access to some of ytt's core capabilities. This
+collection is known as a library (not to be confused with the workspace.Library
+concept).
+
+    (2) => pkg/yttlibrary => (5)
+
+The implementation for ytt's other fundamental feature -- Overlays -- lives
+within this standard library. This allows for both template authors and ytt
+itself to use this powerful editing feature.
+
+    (3) => pkg/yttlibrary/overlay => (5)
+
+"Standard Library" modules that have Go dependencies are included as
+"extensions" to minimize the set of transitive dependencies that come from the
+github.com/vmware-tanzu/carvel-ytt module.
+
+    (1) => pkg/yttlibraryext => (1)
+    (1) => pkg/yttlibraryext/toml => (4)
+
+YAML Enhancements
+
+ytt can enrich a YAML structure with more fine-grained data typing and
+user-defined constraints on values.
+
+    (3) => pkg/schema => (5)
+    (1) => pkg/assertions => (5)
+
+YAML Structures
+
+At the heart of ytt is the ability to parse annotated YAML.
+
+ytt delegates parsing YAML to the de facto standard YAML library
+(https://github.com/go-yaml/yaml/tree/v2). However, ytt needs to store
+additional information about nodes (e.g. templating, type info, processing
+hints, etc.). It does this by converting the output from the standard YAML
+parser into a composite tree of its own yamlmeta.Node structure that can
+hold that metadata.
+
+    (11) => pkg/yamlmeta => (3)
+    (1) => pkg/yamlmeta/internal/yaml.v2 => (0)
+
+Utilities
+
+Finally, there is a collection of supporting features.
+
+One of which provides the implementation of the "fmt" command:
+
+    (1) => pkg/yamlfmt => (1)
+
+The remainder are domain-agnostic utilities that provide either an
+application-level capability or a specialized piece of logic.
+
+    (5) => pkg/cmd/ui => (0)
+    (5) => pkg/orderedmap => (0)
+    (2) => pkg/version => (0)
+    (2) => pkg/feature => (0)
+    (1) => pkg/spell => (0)
+
+Dependencies
+
+Each package's dependencies on other packages within this module are as follows
+(if a package is not listed, it has no dependencies on other packages within
+this module):
+
+    pkg/cmd/template:
+    - pkg/workspace
+    - pkg/workspace/datavalues
+    - pkg/schema
+    - pkg/workspace/ref
+    - pkg/yttlibrary/overlay
+    - pkg/files
+    - pkg/cmd/ui
+    - pkg/template
+    - pkg/filepos
+    - pkg/yamlmeta
+    pkg/workspace:
+    - pkg/assertions
+    - pkg/texttemplate
+    - pkg/workspace/datavalues
+    - pkg/yttlibrary
+    - pkg/schema
+    - pkg/workspace/ref
+    - pkg/yamltemplate
+    - pkg/yttlibrary/overlay
+    - pkg/files
+    - pkg/cmd/ui
+    - pkg/template
+    - pkg/template/core
+    - pkg/filepos
+    - pkg/yamlmeta
+    pkg/assertions:
+    - pkg/feature
+    - pkg/yamltemplate
+    - pkg/template
+    - pkg/filepos
+    - pkg/yamlmeta
+    pkg/yamltemplate:
+    - pkg/texttemplate
+    - pkg/orderedmap
+    - pkg/template
+    - pkg/template/core
+    - pkg/filepos
+    - pkg/yamlmeta
+    pkg/texttemplate:
+    - pkg/template
+    - pkg/filepos
+    pkg/template:
+    - pkg/template/core
+    - pkg/filepos
+    pkg/template/core:
+    - pkg/orderedmap
+    pkg/yamlmeta:
+    - pkg/yamlmeta/internal/yaml.v2
+    - pkg/orderedmap
+    - pkg/filepos
+    pkg/workspace/datavalues:
+    - pkg/schema
+    - pkg/workspace/ref
+    - pkg/template
+    - pkg/template/core
+    - pkg/filepos
+    - pkg/yamlmeta
+    pkg/schema:
+    - pkg/spell
+    - pkg/template
+    - pkg/template/core
+    - pkg/filepos
+    - pkg/yamlmeta
+    pkg/workspace/ref:
+    - pkg/template
+    - pkg/template/core
+    pkg/yttlibrary:
+    - pkg/version
+    - pkg/yttlibrary/overlay
+    - pkg/orderedmap
+    - pkg/template/core
+    - pkg/yamlmeta
+    pkg/yttlibrary/overlay:
+    - pkg/yamltemplate
+    - pkg/template
+    - pkg/template/core
+    - pkg/filepos
+    - pkg/yamlmeta
+    pkg/files:
+    - pkg/cmd/ui
+    pkg/cmd:
+    - pkg/website
+    - pkg/yamlfmt
+    - pkg/yttlibraryext
+    - pkg/cmd/template
+    - pkg/version
+    - pkg/files
+    - pkg/cmd/ui
+    - pkg/yamlmeta
+    pkg/yamlfmt:
+    - pkg/yamlmeta
+    pkg/yttlibraryext:
+    - pkg/yttlibraryext/toml
+    pkg/yttlibraryext/toml:
+    - pkg/yttlibrary
+    - pkg/orderedmap
+    - pkg/template/core
+    - pkg/yamlmeta
+
+*/
+package pkg

pkg/experiments/doc.go

@@ -0,0 +1,12 @@
+// Copyright 2022 VMware, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package experiments provides a global "Feature Flag" facility for
+circuit-breaking pre-GA code.
+
+The intent is to provide a means of selecting a flavor of executable at
+boot; not to toggle experiments on and off. Once settings are loaded from
+the environment variable experiments.Env, they are fixed.
+*/
+package experiments

pkg/experiments/flags.go

@@ -1,14 +1,14 @@
 // Copyright 2022 VMware, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-/*
-Package experiments provides a global "Feature Flag" facility for
-circuit-breaking pre-GA code.
+package experiments
 
-The intent is to provide a means of selecting a flavor of executable at
-boot; not to toggle experiments on and off. Once settings are loaded from
-the environment variable experiments.Env, they are fixed.
+import (
+	"os"
+	"strings"
+)
 
+/*
 Registering a New Experiment
 
 1. implement a getter on this package `Is<experiment-name>Enabled()` and add the experiment to GetEnabled()
@@ -23,14 +23,7 @@ Registering a New Experiment
 
     experiments.ResetForTesting()
     os.Setenv(experiments.Env, "<experiment-name>,<other-experiment-name>,...")
-
 */
-package experiments
-
-import (
-	"os"
-	"strings"
-)
 
 // Env is the OS environment variable with comma-separated names of experiments to enable.
 const Env = "YTTEXPERIMENTS"

pkg/filepos/doc.go

@@ -0,0 +1,16 @@
+// Copyright 2022 VMware, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package filepos provides the concept of Position: a source name (usually a file)
+and line number within that source.
+
+File positions are crucial when reporting errors to the user. It is often
+even more useful to share the actual source line as well. For this reason
+Position also contains a cached copy of the source line at the Position.
+
+Not all Position point within a file (e.g. code that is generated). The
+zero-value of Position (can be created using NewUnknownPosition()) represents
+this case.
+*/
+package filepos

pkg/files/doc.go

@@ -0,0 +1,15 @@
+// Copyright 2022 VMware, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package files provides primitives for enumerating and loading data from various
+file or file-like Source's and for writing output to filesystem files and
+directories.
+
+This allows the rest of ytt code to process logically chunked streams of data
+without becoming entangled in the details of how to read or write data.
+
+ytt processes files differently depending on their Type. For example,
+File instances that are TypeYAML are parsed as YAML.
+*/
+package files

pkg/orderedmap/doc.go

@@ -0,0 +1,11 @@
+// Copyright 2022 VMware, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package orderedmap provides a map implementation where the order of keys is
+maintained (unlike the native Go map).
+
+This flavor of map is crucial in keeping the output of ytt deterministic and
+stable.
+*/
+package orderedmap