diff --git a/helper/resource/state.go b/helper/resource/state.go
index 7a71f1154..871ee3978 100644
--- a/helper/resource/state.go
+++ b/helper/resource/state.go
@@ -34,6 +34,17 @@ type StateChangeConf struct {
 // WaitForState watches an object and waits for it to achieve the state
 // specified in the configuration using the specified Refresh() func,
 // waiting the number of seconds specified in the timeout configuration.
+//
+// If the Refresh function returns a error, exit immediately with that error.
+//
+// If the Refresh function returns a state other than the Target state or one
+// listed in Pending, return immediately with an error.
+//
+// If the Timeout is exceeded before reaching the Target state, return an
+// error.
+//
+// Otherwise, result the result of the first call to the Refresh function to
+// reach the target state.
 func (conf *StateChangeConf) WaitForState() (interface{}, error) {
 	log.Printf("[DEBUG] Waiting for state to become: %s", conf.Target)