diff --git a/prog/kube-peers/annotations.go b/prog/kube-peers/annotations.go
index 7c9064be..fae131e4 100644
--- a/prog/kube-peers/annotations.go
+++ b/prog/kube-peers/annotations.go
@@ -1,3 +1,10 @@
+/*
+In order to keep track of active weave peers, we use annotations on the Kubernetes cluster.
+
+Kubernetes uses etcd to distribute and synchronise these annotations so we don't have to.
+
+This module deals with operations on the peerlist backed by Kubernetes' annotation mechanism.
+*/
 package main
 
 import (
diff --git a/prog/kube-peers/main.go b/prog/kube-peers/main.go
index 6589e74a..81bfda9d 100644
--- a/prog/kube-peers/main.go
+++ b/prog/kube-peers/main.go
@@ -1,3 +1,8 @@
+/*
+Package main deals with weave-net peers on the cluster.
+
+This involves peer management, such as getting the latest peers or removing defunct peers from the cluster
+*/
 package main
 
 import (