diff --git a/cmd/ysvd/main.go b/cmd/ysvd/main.go
index af29a92..8c8c403 100644
--- a/cmd/ysvd/main.go
+++ b/cmd/ysvd/main.go
@@ -1,3 +1,8 @@
+/*
+command ysvd implements the
+
+The "ysv" in ysvd stands for You're so Vain, the song by Carly Simon.
+*/
 package main
 
 import (
diff --git a/doc.go b/doc.go
index 64e3a2a..3bdc744 100644
--- a/doc.go
+++ b/doc.go
@@ -1,2 +1,28 @@
-// package vain implements a vanity service for use by the the go tool
+/*
+Package vain implements a vanity service for use by the the go tool
+
+From the documentation for the go tool, it searches for the following header
+when searching for packages:
+
+	<meta name="go-import" content="import-prefix vcs repo-root">
+
+this is simply a service for aggregating a collection of prefix, vcs, and
+repo-root tuples, and serving the appropriate header over http.
+
+API
+
+In order to add a new package POST a json object to the following route:
+
+	POST /v0/package/
+
+A sample json object:
+
+	{
+		"vcs": "mercurial",
+		"path": "mcquay.me/vain",
+		"repo": "https://s.mcquay.me/sm/vain"
+	}
+
+"path" and "repo" are required; leaving off the "vcs" member defaults to "git".
+*/
 package vain
diff --git a/vain.go b/vain.go
index a9ff6c0..c39e253 100644
--- a/vain.go
+++ b/vain.go
@@ -1,30 +1,3 @@
-/*
-
-From the documentation for the go tool, it searches for the following header
-when searching for packages:
-
-<meta name="go-import" content="import-prefix vcs repo-root">
-
-this is simply a service for aggregating a collection of prefix, vcs, and
-repo-root tuples, and serving the appropriate header over http.
-
-API
-
-In order to add a new package POST a json object to the following route:
-
-POST /v0/package/
-
-A sample json object:
-
-	{
-		"path": "mcquay.me/vain",
-		"repo": "https://s.mcquay.me/sm/vain"
-	}
-
-Naming
-
-the "ysv" in ysvd stands for You're so Vain, the song by Carly Simon.
-*/
 package vain
 
 import "fmt"