Add additional comments on accessing state in API

The new state changes are potentially confusing to people writing
API functions on containers or pods. Add comments to the structs
on how to safely use them.

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

Closes: #1186
Approved by: rhatdan

1 files changed, 10 insertions, 1 deletions

diff --git a/libpod/pod.go b/libpod/pod.go
index 58becfa7a..9ea1f058b 100644
--- a/libpod/pod.go
+++ b/libpod/pod.go
@@ -12,7 +12,16 @@ import (
 	"github.com/sirupsen/logrus"
 )
 
-// Pod represents a group of containers that may share namespaces
+// Pod represents a group of containers that are managed together.
+// Any operations on a Pod that access state must begin with a call to
+// updatePod().
+// There is no guarantee that state exists in a readable state before this call,
+// and even if it does its contents will be out of date and must be refreshed
+// from the database.
+// Generally, this requirement applies only to top-level functions; helpers can
+// assume their callers handled this requirement. Generally speaking, if a
+// function takes the pod lock and accesses any part of state, it should
+// updatePod() immediately after locking.
 // ffjson: skip
 type Pod struct {
 	config *PodConfig