diff --git a/contrib/mesos/pkg/executor/executor.go b/contrib/mesos/pkg/executor/executor.go
index c9a93233e76..6a024fddb93 100644
--- a/contrib/mesos/pkg/executor/executor.go
+++ b/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)
diff --git a/contrib/mesos/pkg/scheduler/meta/doc.go b/contrib/mesos/pkg/scheduler/meta/doc.go
index f7e5aeeeacf..e9d834c94c5 100644
--- a/contrib/mesos/pkg/scheduler/meta/doc.go
+++ b/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
diff --git a/contrib/mesos/pkg/scheduler/plugin.go b/contrib/mesos/pkg/scheduler/plugin.go
index 45f23cc7a26..1fc02e7a000 100644
--- a/contrib/mesos/pkg/scheduler/plugin.go
+++ b/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