pipeline: add a bit more documentation

Make sure that each of the types have at least a bit of documentation.

internal/pipeline/build.go

@@ -5,6 +5,13 @@ import (
 	"github.com/osbuild/osbuild-composer/internal/rpmmd"
 )
 
+// A BuildPipeline represents the build environment for other pipelines. As a
+// general rule, tools required to build pipelines are used from the build
+// environment, rather than from the pipeline itself. Without a specified
+// build environment, the build host's root filesystem would be used, which
+// is not predictable nor reproducible. For the purposes of building the
+// build pipeline, we do use the build host's filesystem, this means we should
+// make minimal assumptions about what's available there.
 type BuildPipeline struct {
 	Pipeline
 
@@ -12,6 +19,8 @@ type BuildPipeline struct {
 	packageSpecs []rpmmd.PackageSpec
 }
 
+// NewBuildPipeline creates a new build pipeline from the repositories in repos
+// and the specified packages.
 func NewBuildPipeline(runner string, repos []rpmmd.RepoConfig, packages []rpmmd.PackageSpec) BuildPipeline {
 	pipeline := BuildPipeline{
 		Pipeline:     New("build", nil, &runner),

internal/pipeline/commit.go

@@ -4,14 +4,18 @@ import (
 	"github.com/osbuild/osbuild-composer/internal/osbuild2"
 )
 
+// OSTreeCommitPipeline represents an ostree with one commit.
 type OSTreeCommitPipeline struct {
 	Pipeline
-	treePipeline *OSPipeline
-	OSVersion    string
+	OSVersion string
 
-	ref string
+	treePipeline *OSPipeline
+	ref          string
 }
 
+// NewOSTreeCommitPipeline creates a new OSTree commit pipeline. The
+// treePipeline is the tree representing the content of the commit.
+// ref is the ref to create the commit under.
 func NewOSTreeCommitPipeline(buildPipeline *BuildPipeline, treePipeline *OSPipeline, ref string) OSTreeCommitPipeline {
 	return OSTreeCommitPipeline{
 		Pipeline:     New("ostree-commit", buildPipeline, nil),
@@ -20,6 +24,7 @@ func NewOSTreeCommitPipeline(buildPipeline *BuildPipeline, treePipeline *OSPipel
 	}
 }
 
+// Ref returns the OSTree ref of the commit.
 func (p OSTreeCommitPipeline) Ref() string {
 	return p.ref
 }

internal/pipeline/commit_server_tree.go

@@ -8,6 +8,8 @@ import (
 	"github.com/osbuild/osbuild-composer/internal/rpmmd"
 )
 
+// An OSTreeCommitServerTreePipeline contains an nginx server serving
+// an embedded ostree commit.
 type OSTreeCommitServerTreePipeline struct {
 	Pipeline
 	// TODO: should this be configurable?
@@ -20,6 +22,11 @@ type OSTreeCommitServerTreePipeline struct {
 	listenPort      string
 }
 
+// NewOSTreeCommitServerTreePipeline creates a new pipeline. The content
+// is built from repos and packages, which must contain nginx. commitPipeline
+// is a pipeline producing an ostree commit to be served. nginxConfigPath
+// is the path to the main nginx config file and listenPort is the port
+// nginx will be listening on.
 func NewOSTreeCommitServerTreePipeline(buildPipeline *BuildPipeline,
 	repos []rpmmd.RepoConfig,
 	packageSpecs []rpmmd.PackageSpec,

internal/pipeline/iso.go

@@ -4,6 +4,8 @@ import (
 	"github.com/osbuild/osbuild-composer/internal/osbuild2"
 )
 
+// An ISOPipeline represents a bootable ISO file created from an
+// an existing ISOTreePipeline.
 type ISOPipeline struct {
 	Pipeline
 	ISOLinux bool

internal/pipeline/iso_tree.go

@@ -9,6 +9,9 @@ import (
 	"github.com/osbuild/osbuild-composer/internal/osbuild2"
 )
 
+// An ISOTreePipeline represents a tree containing the anaconda installer,
+// configuration in terms of a kickstart file, as well as an embedded
+// payload to be installed.
 type ISOTreePipeline struct {
 	Pipeline
 	// TODO: review optional and mandatory fields and their meaning

internal/pipeline/live.go

@@ -4,6 +4,8 @@ import (
 	"github.com/osbuild/osbuild-composer/internal/osbuild2"
 )
 
+// A LiveImgPipeline represents a raw image file which can be booted in a
+// hypervisor. It is created from an existing OSPipeline.
 type LiveImgPipeline struct {
 	Pipeline
 	treePipeline *OSPipeline

internal/pipeline/oci_container.go

@@ -4,6 +4,8 @@ import (
 	"github.com/osbuild/osbuild-composer/internal/osbuild2"
 )
 
+// An OCIContainerPipeline represents an OCI container, containing a filesystem
+// tree created by another Pipeline.
 type OCIContainerPipeline struct {
 	Pipeline
 	Cmd          []string