diff --git a/broker/broker.go b/broker/broker.go
index c387962b..d2e60d2e 100644
--- a/broker/broker.go
+++ b/broker/broker.go
@@ -1,3 +1,4 @@
+// Package broker is an interface used for asynchronous messaging
 package broker
 
 // Broker is an interface used for asynchronous messaging.
diff --git a/broker/doc.go b/broker/doc.go
deleted file mode 100644
index f0bff3c4..00000000
--- a/broker/doc.go
+++ /dev/null
@@ -1,4 +0,0 @@
-/*
-Package broker is an interface used for asynchronous messaging.
-*/
-package broker
diff --git a/client/client.go b/client/client.go
index e7a8536d..55499aff 100644
--- a/client/client.go
+++ b/client/client.go
@@ -1,3 +1,4 @@
+// Package client is an interface for an RPC client
 package client
 
 import (
diff --git a/client/doc.go b/client/doc.go
deleted file mode 100644
index 3954b032..00000000
--- a/client/doc.go
+++ /dev/null
@@ -1,23 +0,0 @@
-/*
-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/cmd.go b/cmd/cmd.go
index cebce22c..26401875 100644
--- a/cmd/cmd.go
+++ b/cmd/cmd.go
@@ -1,3 +1,4 @@
+// Package cmd is an interface for parsing the command line
 package cmd
 
 import (
diff --git a/cmd/doc.go b/cmd/doc.go
deleted file mode 100644
index 1393799d..00000000
--- a/cmd/doc.go
+++ /dev/null
@@ -1,4 +0,0 @@
-/*
-Package cmd is an interface for parsing the command line.
-*/
-package cmd
diff --git a/codec/codec.go b/codec/codec.go
index 1a05c00b..edc659ff 100644
--- a/codec/codec.go
+++ b/codec/codec.go
@@ -1,3 +1,4 @@
+// Package codec is an interface for encoding messages
 package codec
 
 import (
diff --git a/codec/doc.go b/codec/doc.go
deleted file mode 100644
index 3e1b3e17..00000000
--- a/codec/doc.go
+++ /dev/null
@@ -1,4 +0,0 @@
-/*
-Package codec is an interface for encoding messages.
-*/
-package codec
diff --git a/errors/doc.go b/errors/doc.go
deleted file mode 100644
index 618c419a..00000000
--- a/errors/doc.go
+++ /dev/null
@@ -1,4 +0,0 @@
-/*
-Package errors is an interface for defining detailed errors.
-*/
-package errors
diff --git a/errors/errors.go b/errors/errors.go
index f61a772f..99d0a309 100644
--- a/errors/errors.go
+++ b/errors/errors.go
@@ -1,3 +1,4 @@
+// Package errors is an interface for defining detailed errors
 package errors
 
 import (
diff --git a/metadata/doc.go b/metadata/doc.go
deleted file mode 100644
index e60c020b..00000000
--- a/metadata/doc.go
+++ /dev/null
@@ -1,4 +0,0 @@
-/*
-Package metadata is a way of defining message headers.
-*/
-package metadata
diff --git a/metadata/metadata.go b/metadata/metadata.go
index 380740c7..dc65d605 100644
--- a/metadata/metadata.go
+++ b/metadata/metadata.go
@@ -1,3 +1,4 @@
+// Package metadata is a way of defining message headers
 package metadata
 
 import (
diff --git a/registry/doc.go b/registry/doc.go
deleted file mode 100644
index 8edd49fd..00000000
--- a/registry/doc.go
+++ /dev/null
@@ -1,4 +0,0 @@
-/*
-Package registry is an interface for service discovery.
-*/
-package registry
diff --git a/registry/registry.go b/registry/registry.go
index 8a979424..f3465bf3 100644
--- a/registry/registry.go
+++ b/registry/registry.go
@@ -1,3 +1,4 @@
+// Package registry is an interface for service discovery
 package registry
 
 import (
diff --git a/selector/doc.go b/selector/doc.go
deleted file mode 100644
index d0ca4295..00000000
--- a/selector/doc.go
+++ /dev/null
@@ -1,8 +0,0 @@
-/*
-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 6961040a..dab26de2 100644
--- a/selector/selector.go
+++ b/selector/selector.go
@@ -1,3 +1,4 @@
+// Package selector is a way to load balance service nodes
 package selector
 
 import (
diff --git a/server/doc.go b/server/doc.go
deleted file mode 100644
index c3510d46..00000000
--- a/server/doc.go
+++ /dev/null
@@ -1,31 +0,0 @@
-/*
-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 79e9e5de..986cacb3 100644
--- a/server/server.go
+++ b/server/server.go
@@ -1,3 +1,4 @@
+// Package server is an interface for a micro server
 package server
 
 import (
diff --git a/transport/doc.go b/transport/doc.go
deleted file mode 100644
index a8300db6..00000000
--- a/transport/doc.go
+++ /dev/null
@@ -1,4 +0,0 @@
-/*
-Package is an interface for synchronous communication.
-*/
-package transport
diff --git a/transport/transport.go b/transport/transport.go
index 25dfb146..8f3e0879 100644
--- a/transport/transport.go
+++ b/transport/transport.go
@@ -1,3 +1,4 @@
+// Package is an interface for synchronous communication
 package transport
 
 import (