packer: Additional comments

packer/build.go

@@ -26,6 +26,9 @@ type Build interface {
 	// enabled by adding the additional key "packer_debug" to boolean
 	// true in the configuration of the various components. This must
 	// be called prior to Prepare.
+	//
+	// When SetDebug is set to true, parallelism between builds is
+	// strictly prohibited.
 	SetDebug(bool)
 }
 

packer/builder.go

@@ -2,6 +2,14 @@ package packer
 
 // Implementers of Builder are responsible for actually building images
 // on some platform given some configuration.
+//
+// In addition to the documentation on Prepare above: Prepare is sometimes
+// configured with a `map[string]interface{}` that has a key "packer_debug".
+// This is a boolean value. If it is set to true, then the builder should
+// enable a debug mode which allows builder developers and advanced users
+// to introspect what is going on during a build. During debug builds,
+// parallelism is strictly disabled, so it is safe to request input from
+// stdin and so on.
 type Builder interface {
 	// Prepare is responsible for configuring the builder and validating
 	// that configuration. Any setup should be done in this method. Note that