Update documentation for the State interface

Include details on how namespaces interact with the
state.

Signed-off-by: Matthew Heon <matthew.heon@gmail.com>

1 files changed, 72 insertions, 33 deletions

diff --git a/libpod/state.go b/libpod/state.go
index 6239e399a..1b82349b3 100644
--- a/libpod/state.go
+++ b/libpod/state.go
@@ -10,70 +10,109 @@ type State interface {
 	Refresh() error
 
 	// SetNamespace() sets the namespace for the store, and will determine
-	// what containers are retrieved with container and pod retrieval calls
+	// what containers are retrieved with container and pod retrieval calls.
+	// A namespace of "", the empty string, acts as no namespace, and
+	// containers and pods in all namespaces will be returned.
 	SetNamespace(ns string) error
 
-	// Return a container from the database from its full ID
+	// Return a container from the database from its full ID.
+	// If the container is not in the set namespace, an error will be
+	// returned.
 	Container(id string) (*Container, error)
 	// Return a container from the database by full or partial ID or full
-	// name
+	// name.
+	// Containers not in the set namespace will be ignored.
 	LookupContainer(idOrName string) (*Container, error)
-	// Check if a container with the given full ID exists in the database
+	// Check if a container with the given full ID exists in the database.
+	// If the container exists but is not in the set namespace, false will
+	// be returned.
 	HasContainer(id string) (bool, error)
-	// Adds container to state
-	// The container cannot be part of a pod
+	// Adds container to state.
+	// The container cannot be part of a pod.
 	// The container must have globally unique name and ID - pod names and
-	// IDs also conflict with container names and IDs
+	// IDs also conflict with container names and IDs.
+	// The container must be in the set namespace if a namespace has been
+	// set.
+	// All containers this container depends on must be part of the same
+	// namespace and must not be joined to a pod.
 	AddContainer(ctr *Container) error
-	// Removes container from state
-	// Containers that are part of pods must use RemoveContainerFromPod
+	// Removes container from state.
+	// Containers that are part of pods must use RemoveContainerFromPod.
+	// The container must be part of the set namespace.
 	RemoveContainer(ctr *Container) error
-	// UpdateContainer updates a container's state from the backing store
+	// UpdateContainer updates a container's state from the backing store.
+	// The container must be part of the set namespace.
 	UpdateContainer(ctr *Container) error
-	// SaveContainer saves a container's current state to the backing store
+	// SaveContainer saves a container's current state to the backing store.
+	// The container must be part of the set namespace.
 	SaveContainer(ctr *Container) error
 	// ContainerInUse checks if other containers depend upon a given
-	// container
+	// container.
 	// It returns a slice of the IDs of containers which depend on the given
 	// container. If the slice is empty, no container depend on the given
 	// container.
-	// A container cannot be removed if other containers depend on it
+	// A container cannot be removed if other containers depend on it.
+	// The container being checked must be part of the set namespace.
 	ContainerInUse(ctr *Container) ([]string, error)
-	// Retrieves all containers presently in state
+	// Retrieves all containers presently in state.
+	// If a namespace is set, only containers within the namespace will be
+	// returned.
 	AllContainers() ([]*Container, error)
 
-	// Accepts full ID of pod
+	// Accepts full ID of pod.
+	// If the pod given is not in the set namespace, an error will be
+	// returned.
 	Pod(id string) (*Pod, error)
-	// Accepts full or partial IDs (as long as they are unique) and names
+	// Accepts full or partial IDs (as long as they are unique) and names.
+	// Pods not in the set namespace are ignored.
 	LookupPod(idOrName string) (*Pod, error)
-	// Checks if a pod with the given ID is present in the state
+	// Checks if a pod with the given ID is present in the state.
+	// If the given pod is not in the set namespace, false is returned.
 	HasPod(id string) (bool, error)
-	// Check if a pod has a container with the given ID
+	// Check if a pod has a container with the given ID.
+	// The pod must be part of the set namespace.
 	PodHasContainer(pod *Pod, ctrID string) (bool, error)
-	// Get the IDs of all containers in a pod
+	// Get the IDs of all containers in a pod.
+	// The pod must be part of the set namespace.
 	PodContainersByID(pod *Pod) ([]string, error)
-	// Get all the containers in a pod
+	// Get all the containers in a pod.
+	// The pod must be part of the set namespace.
 	PodContainers(pod *Pod) ([]*Container, error)
-	// Adds pod to state
+	// Adds pod to state.
+	// The pod must be part of the set namespace.
+	// The pod's name and ID must be globally unique.
 	AddPod(pod *Pod) error
-	// Removes pod from state
-	// Only empty pods can be removed from the state
+	// Removes pod from state.
+	// Only empty pods can be removed from the state.
+	// The pod must be part of the set namespace.
 	RemovePod(pod *Pod) error
-	// Remove all containers from a pod
+	// Remove all containers from a pod.
 	// Used to simultaneously remove containers that might otherwise have
-	// dependency issues
-	// Will fail if a dependency outside the pod is encountered
+	// dependency issues.
+	// Will fail if a dependency outside the pod is encountered.
+	// The pod must be part of the set namespace.
 	RemovePodContainers(pod *Pod) error
-	// AddContainerToPod adds a container to an existing pod
-	// The container given will be added to the state and the pod
+	// AddContainerToPod adds a container to an existing pod.
+	// The container given will be added to the state and the pod.
+	// The container and its dependencies must be part of the given pod,
+	// and the given pod's namespace.
+	// The pod must be part of the set namespace.
+	// The pod must already exist in the state.
+	// The container's name and ID must be globally unique.
 	AddContainerToPod(pod *Pod, ctr *Container) error
-	// RemoveContainerFromPod removes a container from an existing pod
-	// The container will also be removed from the state
+	// RemoveContainerFromPod removes a container from an existing pod.
+	// The container will also be removed from the state.
+	// The container must be in the given pod, and the pod must be in the
+	// set namespace.
 	RemoveContainerFromPod(pod *Pod, ctr *Container) error
-	// UpdatePod updates a pod's state from the database
+	// UpdatePod updates a pod's state from the database.
+	// The pod must be in the set namespace.
 	UpdatePod(pod *Pod) error
-	// SavePod saves a pod's state to the database
+	// SavePod saves a pod's state to the database.
+	// The pod must be in the set namespace.
 	SavePod(pod *Pod) error
-	// Retrieves all pods presently in state
+	// Retrieves all pods presently in state.
+	// If a namespace has been set, only pods in that namespace will be
+	// returned.
 	AllPods() ([]*Pod, error)
 }