additional comments as per code review

contrib/mesos/pkg/executor/executor.go

@@ -472,7 +472,8 @@ func (k *KubernetesExecutor) launchTask(driver bindings.ExecutorDriver, taskId s
 	task.podName = podFullName
 	k.pods[podFullName] = pod
 
-	// send the latest snapshot of the set of pods to the kubelet via the pod update channel
+	// send the latest snapshot of the set of pods to the kubelet via the pod update channel.
+	// this results in the kubelet spinning up the new pod.
 	update := kubelet.PodUpdate{Op: kubelet.SET}
 	for _, p := range k.pods {
 		update.Pods = append(update.Pods, p)

contrib/mesos/pkg/scheduler/meta/doc.go

@@ -15,5 +15,8 @@ limitations under the License.
 */
 
 // Package meta defines framework constants used as keys in k8s annotations
-// that are attached to k8s pods
+// that are attached to k8s pods. The scheduler uses some of these annotations
+// for reconciliation upon failover. Other annotations are used as part of
+// the host-to-pod port-mapping implementation understood by the k8s-mesos
+// scheduler and custom endpoints-controller implementation.
 package meta

contrib/mesos/pkg/scheduler/plugin.go

@@ -56,7 +56,7 @@ const (
 type schedulerInterface interface {
 	sync.Locker // synchronize scheduler plugin operations
 	SlaveIndex
-	algorithm() PodScheduleFunc
+	algorithm() PodScheduleFunc // see types.go
 	offers() offers.Registry
 	tasks() podtask.Registry