diff --git a/broker/doc.go b/broker/doc.go
new file mode 100644
index 00000000..f0bff3c4
--- /dev/null
+++ b/broker/doc.go
@@ -0,0 +1,4 @@
+/*
+Package broker is an interface used for asynchronous messaging.
+*/
+package broker
diff --git a/client/client.go b/client/client.go
index 404a9132..6f4859d2 100644
--- a/client/client.go
+++ b/client/client.go
@@ -1,24 +1,3 @@
-/*
-Package client provides a method to make synchronous, asynchronous and
-streaming requests to services. By default json and protobuf codecs are
-supported.
-
-	import "github.com/micro/go-micro/client"
-
-	c := client.NewClient()
-
-	req := c.NewRequest("go.micro.srv.greeter", "Greeter.Hello", &greeter.Request{
-		Name: "John",
-	})
-
-	rsp := &greeter.Response{}
-
-	if err := c.Call(context.Background(), req, rsp); err != nil {
-		return err
-	}
-
-	fmt.Println(rsp.Msg)
-*/
 package client
 
 import (
diff --git a/client/doc.go b/client/doc.go
new file mode 100644
index 00000000..3954b032
--- /dev/null
+++ b/client/doc.go
@@ -0,0 +1,23 @@
+/*
+Package client is an interface for making requests.
+
+It provides a method to make synchronous, asynchronous and streaming requests to services.
+By default json and protobuf codecs are supported.
+
+        import "github.com/micro/go-micro/client"
+
+        c := client.NewClient()
+
+        req := c.NewRequest("go.micro.srv.greeter", "Greeter.Hello", &greeter.Request{
+                Name: "John",
+        })
+
+        rsp := &greeter.Response{}
+
+        if err := c.Call(context.Background(), req, rsp); err != nil {
+                return err
+        }
+
+        fmt.Println(rsp.Msg)
+*/
+package client
diff --git a/cmd/doc.go b/cmd/doc.go
new file mode 100644
index 00000000..1393799d
--- /dev/null
+++ b/cmd/doc.go
@@ -0,0 +1,4 @@
+/*
+Package cmd is an interface for parsing the command line.
+*/
+package cmd
diff --git a/codec/doc.go b/codec/doc.go
new file mode 100644
index 00000000..3e1b3e17
--- /dev/null
+++ b/codec/doc.go
@@ -0,0 +1,4 @@
+/*
+Package codec is an interface for encoding messages.
+*/
+package codec
diff --git a/errors/doc.go b/errors/doc.go
new file mode 100644
index 00000000..618c419a
--- /dev/null
+++ b/errors/doc.go
@@ -0,0 +1,4 @@
+/*
+Package errors is an interface for defining detailed errors.
+*/
+package errors
diff --git a/metadata/doc.go b/metadata/doc.go
new file mode 100644
index 00000000..e60c020b
--- /dev/null
+++ b/metadata/doc.go
@@ -0,0 +1,4 @@
+/*
+Package metadata is a way of defining message headers.
+*/
+package metadata
diff --git a/registry/doc.go b/registry/doc.go
new file mode 100644
index 00000000..8edd49fd
--- /dev/null
+++ b/registry/doc.go
@@ -0,0 +1,4 @@
+/*
+Package registry is an interface for service discovery.
+*/
+package registry
diff --git a/selector/doc.go b/selector/doc.go
new file mode 100644
index 00000000..d0ca4295
--- /dev/null
+++ b/selector/doc.go
@@ -0,0 +1,8 @@
+/*
+Package selector is a way to load balance service nodes.
+
+It algorithmically filter and return nodes required by the client or any other system.
+Selector's implemented by Micro build on the registry but it's of optional use. One could
+provide a static Selector that has a fixed pool.
+*/
+package selector
diff --git a/selector/selector.go b/selector/selector.go
index e7dd8996..6961040a 100644
--- a/selector/selector.go
+++ b/selector/selector.go
@@ -1,9 +1,3 @@
-/*
-The Selector package provides a way to algorithmically filter and return
-nodes required by the client or any other system. Selector's implemented
-by Micro build on the registry but it's of optional use. One could
-provide a static Selector that has a fixed pool.
-*/
 package selector
 
 import (
diff --git a/server/doc.go b/server/doc.go
new file mode 100644
index 00000000..c3510d46
--- /dev/null
+++ b/server/doc.go
@@ -0,0 +1,31 @@
+/*
+Package server is an interface for a micro server.
+
+It represents a server instance in go-micro which handles synchronous
+requests via handlers and asynchronous requests via subscribers that
+register with a broker.
+
+The server combines the all the packages in go-micro to create a whole unit
+used for building applications including discovery, client/server communication
+and pub/sub.
+
+        import "github.com/micro/go-micro/server"
+
+        type Greeter struct {}
+
+        func (g *Greeter) Hello(ctx context.Context, req *greeter.Request, rsp *greeter.Response) error {
+                rsp.Msg = "Hello " + req.Name
+                return nil
+        }
+
+        s := server.NewServer()
+
+
+        s.Handle(
+                s.NewHandler(&Greeter{}),
+        )
+
+        s.Start()
+
+*/
+package server
diff --git a/server/server.go b/server/server.go
index 95aca9e7..79e9e5de 100644
--- a/server/server.go
+++ b/server/server.go
@@ -1,31 +1,3 @@
-/*
-Server represents a server instance in go-micro which handles synchronous
-requests via handlers and asynchronous requests via subscribers that
-register with a broker.
-
-The server combines the all the packages in go-micro to create a whole unit
-used for building applications including discovery, client/server communication
-and pub/sub.
-
-	import "github.com/micro/go-micro/server"
-
-	type Greeter struct {}
-
-	func (g *Greeter) Hello(ctx context.Context, req *greeter.Request, rsp *greeter.Response) error {
-		rsp.Msg = "Hello " + req.Name
-		return nil
-	}
-
-	s := server.NewServer()
-
-
-	s.Handle(
-		s.NewHandler(&Greeter{}),
-	)
-
-	s.Start()
-
-*/
 package server
 
 import (
diff --git a/transport/doc.go b/transport/doc.go
new file mode 100644
index 00000000..a8300db6
--- /dev/null
+++ b/transport/doc.go
@@ -0,0 +1,4 @@
+/*
+Package is an interface for synchronous communication.
+*/
+package transport