diff --git a/blockservice/worker/bench/main.go b/blockservice/worker/bench/main.go
index 82c3dee13..c23770f78 100644
--- a/blockservice/worker/bench/main.go
+++ b/blockservice/worker/bench/main.go
@@ -1,3 +1,12 @@
+/*
+Benchmark github.com/ipfs/go-ipfs/blockservice/worker.
+
+Loop over a range of workers and buffer sizes and measure the time it
+per block-transfer operation for each value.  Run with:
+
+  $ go run "${GOPATH}/src/github.com/ipfs/go-ipfs/blockservice/worker/bench/main.go"
+*/
+
 package main
 
 import (
diff --git a/commands/command.go b/commands/command.go
index f819b0440..e9774b85b 100644
--- a/commands/command.go
+++ b/commands/command.go
@@ -1,3 +1,11 @@
+/*
+Package commands provides an API for defining and parsing commands.
+
+Supporting nested commands, options, arguments, etc.  The commands
+package also supports a collection of marshallers for presenting
+output to the user, including text, JSON, and XML marshallers.
+*/
+
 package commands
 
 import (
diff --git a/core/commands/commands.go b/core/commands/commands.go
index 8b7080493..1d65cdbad 100644
--- a/core/commands/commands.go
+++ b/core/commands/commands.go
@@ -1,3 +1,10 @@
+/*
+Package commands implements the IPFS command interface
+
+Using github.com/ipfs/go-ipfs/commands to define the command line and
+HTTP APIs.  This is the interface available to folks consuming IPFS
+from outside of the Go language.
+*/
 package commands
 
 import (
diff --git a/core/core.go b/core/core.go
index 40d5cbb70..877ffe9c0 100644
--- a/core/core.go
+++ b/core/core.go
@@ -1,5 +1,12 @@
-// package core implements the IpfsNode object and methods for constructing
-// and properly setting it up.
+/*
+Package core implements the IpfsNode object and related methods.
+
+Packages underneath core/ provide a (relatively) stable, low-level API
+to carry out most IPFS-related tasks.  For more details on the other
+interfaces and how core/... fits into the bigger IPFS picture, see:
+
+  $ godoc github.com/ipfs/go-ipfs
+*/
 package core
 
 import (
diff --git a/core/corehttp/corehttp.go b/core/corehttp/corehttp.go
index ff9bac704..e8852baaf 100644
--- a/core/corehttp/corehttp.go
+++ b/core/corehttp/corehttp.go
@@ -1,3 +1,7 @@
+/*
+Package corehttp provides utilities for the webui, gateways, and other
+high-level HTTP interfaces to IPFS.
+*/
 package corehttp
 
 import (
diff --git a/core/corerepo/pinning.go b/core/corerepo/pinning.go
index 81acba43e..cf2762713 100644
--- a/core/corerepo/pinning.go
+++ b/core/corerepo/pinning.go
@@ -1,3 +1,16 @@
+/*
+Package corerepo provides pinning and garbage collection for local
+IPFS block services.
+
+IPFS nodes will keep local copies of any object that have either been
+added or requested locally.  Not all of these objects are worth
+preserving forever though, so the node adminstrator can pin objects
+they want to keep and unpin objects that they don't care about.
+
+Garbage collection sweeps iterate through the local block store
+removing objects that aren't pinned, which frees storage space for new
+objects.
+*/
 package corerepo
 
 import (
diff --git a/doc.go b/doc.go
index 4dadc4e6a..fdf2f6909 100644
--- a/doc.go
+++ b/doc.go
@@ -1,2 +1,27 @@
-// IPFS is a global, versioned, peer-to-peer filesystem
+/*
+IPFS is a global, versioned, peer-to-peer filesystem
+
+There are sub-packages within the ipfs package for various low-level
+utilities, which are in turn assembled into:
+
+core/...:
+  The low-level API that gives consumers all the knobs they need,
+  which we try hard to keep stable.
+shell/...:
+  The high-level API that gives consumers easy access to common
+  operations (e.g. create a file node from a reader without wrapping
+  with metadata). We work really hard to keep this stable.
+
+Then on top of the core/... and shell/... Go APIs, we have:
+
+cmd/...:
+  Command-line executables
+test/...:
+  Integration tests, etc.
+
+To avoid cyclic imports, imports should never pull in higher-level
+APIs into a lower-level package.  For example, you could import all of
+core and shell from cmd/... or test/..., but you couldn't import any
+of shell from core/....
+*/
 package ipfs