docs: document podman module

podman/main.go

@@ -1,3 +1,4 @@
+// The Podman package handles any interactions with Podman entities or state.
 package podman
 
 import (
@@ -7,14 +8,12 @@ import (
 	service_definition "spud/service_definition"
 )
 
-/*
- * Creates a Podman volume of name `name` if it does not exist.
- *
- * If the volume exists, then behaviour depends on `existsOk`:
- * - If `existsOk` is truthy, then the already-exists error is ignored and
- *   nothing is done;
- * - Else, an error is returned.
- */
+// Creates a Podman volume of name `name` if it does not exist.
+//
+// If the volume exists, then behaviour depends on `existsOk`:
+// - If `existsOk` is truthy, then the already-exists error is ignored and
+//   nothing is done;
+// - Else, an error is returned.
 func CreateVolume(name string, existsOk bool) error {
 	args := []string{"volume", "create", name}
 
@@ -34,10 +33,10 @@ func CreateVolume(name string, existsOk bool) error {
 	return nil
 }
 
-/*
- * Creates a Podman pod to keep related containers together.
- *
- */
+// Creates a Podman pod to keep related containers together.
+//
+// The pod created will expose ports necessary for individual containers
+// to be accessible from the host.
 func CreatePod(name string, ports []service_definition.PortMapping) error {
 	args := []string{"pod", "create", "--replace"}
 
@@ -59,9 +58,7 @@ func CreatePod(name string, ports []service_definition.PortMapping) error {
 	return nil
 }
 
-/*
- * Stops a running pod.
- */
+// Stops a running pod.
 func StopPod(name string) error {
 	args := []string{"pod", "stop", name}
 
@@ -77,9 +74,10 @@ func StopPod(name string) error {
 
 }
 
-/*
- * Creates individual containers.
- */
+// Creates individual containers.
+// 
+// Individual containers do not expose any ports by themselves, these
+// are handled by the pod that wraps the containers.
 func CreateContainer(definition service_definition.ContainerDefinition, knownVolumes map[string]string, service string) error {
 	namespacedContainerName := service + "_" + definition.Name