diff --git a/utils/pagination/controller.go b/utils/pagination/controller.go
index 5a0d4e99..da92bd69 100644
--- a/utils/pagination/controller.go
+++ b/utils/pagination/controller.go
@@ -12,55 +12,6 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-// Usage
-//
-// In your beego.Controller:
-//
-// package controllers
-//
-// import "github.com/astaxie/beego/utils/pagination"
-//
-// type PostsController struct {
-// beego.Controller
-// }
-//
-// func (this *PostsController) ListAllPosts() {
-// // sets this.Data["paginator"] with the current offset (from the url query param)
-// postsPerPage := 20
-// paginator := pagination.SetPaginator(this, postsPerPage, CountPosts())
-//
-// // fetch the next 20 posts
-// this.Data["posts"] = ListPostsByOffsetAndLimit(paginator.Offset(), postsPerPage)
-// }
-//
-//
-// In your view templates:
-//
-// {{if .paginator.HasPages}}
-//
-// {{end}}
-//
-// See also http://beego.me/docs/mvc/view/page.md
package pagination
import (
diff --git a/utils/pagination/doc.go b/utils/pagination/doc.go
new file mode 100644
index 00000000..db8cd57e
--- /dev/null
+++ b/utils/pagination/doc.go
@@ -0,0 +1,59 @@
+/*
+
+The pagination package provides utilities to setup a paginator within the
+context of a http request.
+
+Usage
+
+In your beego.Controller:
+
+ package controllers
+
+ import "github.com/astaxie/beego/utils/pagination"
+
+ type PostsController struct {
+ beego.Controller
+ }
+
+ func (this *PostsController) ListAllPosts() {
+ // sets this.Data["paginator"] with the current offset (from the url query param)
+ postsPerPage := 20
+ paginator := pagination.SetPaginator(this, postsPerPage, CountPosts())
+
+ // fetch the next 20 posts
+ this.Data["posts"] = ListPostsByOffsetAndLimit(paginator.Offset(), postsPerPage)
+ }
+
+
+In your view templates:
+
+ {{if .paginator.HasPages}}
+
+ {{end}}
+
+See also
+
+http://beego.me/docs/mvc/view/page.md
+
+*/
+package pagination