Better documentation

context.go

@@ -171,19 +171,19 @@ func (c *Context) MustGet(key string) interface{} {
 /************ INPUT DATA ************/
 /************************************/
 
-/** Shortcut for c.Request.URL.Query().Get(key) */
+// Shortcut for c.Request.URL.Query().Get(key)
 func (c *Context) Query(key string) (va string) {
 	va, _ = c.query(key)
 	return
 }
 
-/** Shortcut for c.Request.PostFormValue(key) */
+// Shortcut for c.Request.PostFormValue(key)
 func (c *Context) PostForm(key string) (va string) {
 	va, _ = c.postForm(key)
 	return
 }
 
-/** Shortcut for c.Params.ByName(key) */
+// Shortcut for c.Params.ByName(key)
 func (c *Context) Param(key string) string {
 	return c.Params.ByName(key)
 }

errors.go

@@ -66,14 +66,18 @@ func (msg *Error) JSON() interface{} {
 	return json
 }
 
+// Implements the json.Marshaller interface
 func (msg *Error) MarshalJSON() ([]byte, error) {
 	return json.Marshal(msg.JSON())
 }
 
+// Implements the error interface
 func (msg *Error) Error() string {
 	return msg.Err.Error()
 }
 
+// Returns a readonly copy filterd the byte.
+// ie ByType(gin.ErrorTypePublic) returns a slice of errors with type=ErrorTypePublic
 func (a errorMsgs) ByType(typ ErrorType) errorMsgs {
 	if len(a) == 0 {
 		return a
@@ -87,6 +91,8 @@ func (a errorMsgs) ByType(typ ErrorType) errorMsgs {
 	return result
 }
 
+// Returns the last error in the slice. It returns nil if the array is empty.
+// Shortcut for errors[len(errors)-1]
 func (a errorMsgs) Last() *Error {
 	length := len(a)
 	if length == 0 {
@@ -95,6 +101,14 @@ func (a errorMsgs) Last() *Error {
 	return a[length-1]
 }
 
+// Returns an array will all the error messages.
+// Example
+// ```
+// c.Error(errors.New("first"))
+// c.Error(errors.New("second"))
+// c.Error(errors.New("third"))
+// c.Errors.Errors() // == []string{"first", "second", "third"}
+// ``
 func (a errorMsgs) Errors() []string {
 	if len(a) == 0 {
 		return []string{}

fs.go

@@ -14,6 +14,10 @@ type (
 	}
 )
 
+// It returns a http.Filesystem that can be used by http.FileServer(). It is used interally
+// in router.Static().
+// if listDirectory == true, then it works the same as http.Dir() otherwise it returns
+// a filesystem that prevents http.FileServer() to list the directory files.
 func Dir(root string, listDirectory bool) http.FileSystem {
 	fs := http.Dir(root)
 	if listDirectory {
@@ -23,6 +27,7 @@ func Dir(root string, listDirectory bool) http.FileSystem {
 	}
 }
 
+// Conforms to http.Filesystem
 func (fs onlyfilesFS) Open(name string) (http.File, error) {
 	f, err := fs.fs.Open(name)
 	if err != nil {
@@ -31,6 +36,7 @@ func (fs onlyfilesFS) Open(name string) (http.File, error) {
 	return neuteredReaddirFile{f}, nil
 }
 
+// Overrides the http.File default implementation
 func (f neuteredReaddirFile) Readdir(count int) ([]os.FileInfo, error) {
 	// this disables directory listing
 	return nil, nil

gin.go

@@ -123,11 +123,15 @@ func (engine *Engine) NoRoute(handlers ...HandlerFunc) {
 	engine.rebuild404Handlers()
 }
 
+// Sets the handlers called when... TODO
 func (engine *Engine) NoMethod(handlers ...HandlerFunc) {
 	engine.noMethod = handlers
 	engine.rebuild405Handlers()
 }
 
+// Attachs a global middleware to the router. ie. the middlewares attached though Use() will be
+// included in the handlers chain for every single request. Even 404, 405, static files...
+// For example, this is the right place for a logger or error management middleware.
 func (engine *Engine) Use(middlewares ...HandlerFunc) {
 	engine.RouterGroup.Use(middlewares...)
 	engine.rebuild404Handlers()
@@ -166,6 +170,9 @@ func (engine *Engine) addRoute(method, path string, handlers HandlersChain) {
 	root.addRoute(path, handlers)
 }
 
+// The router is attached to a http.Server and starts listening and serving HTTP requests.
+// It is a shortcut for http.ListenAndServe(addr, router)
+// Note: this method will block the calling goroutine undefinitelly unless an error happens.
 func (engine *Engine) Run(addr string) (err error) {
 	debugPrint("Listening and serving HTTP on %s\n", addr)
 	defer func() { debugPrintError(err) }()
@@ -174,6 +181,9 @@ func (engine *Engine) Run(addr string) (err error) {
 	return
 }
 
+// The router is attached to a http.Server and starts listening and serving HTTPS requests.
+// It is a shortcut for http.ListenAndServeTLS(addr, certFile, keyFile, router)
+// Note: this method will block the calling goroutine undefinitelly unless an error happens.
 func (engine *Engine) RunTLS(addr string, certFile string, keyFile string) (err error) {
 	debugPrint("Listening and serving HTTPS on %s\n", addr)
 	defer func() { debugPrintError(err) }()
@@ -182,6 +192,9 @@ func (engine *Engine) RunTLS(addr string, certFile string, keyFile string) (err
 	return
 }
 
+// The router is attached to a http.Server and starts listening and serving HTTP requests
+// through the specified unix socket (ie. a file)
+// Note: this method will block the calling goroutine undefinitelly unless an error happens.
 func (engine *Engine) RunUnix(file string) (err error) {
 	debugPrint("Listening and serving HTTP on unix:/%s", file)
 	defer func() { debugPrintError(err) }()
@@ -196,7 +209,7 @@ func (engine *Engine) RunUnix(file string) (err error) {
 	return
 }
 
-// ServeHTTP makes the router implement the http.Handler interface.
+// Conforms to the http.Handler interface.
 func (engine *Engine) ServeHTTP(w http.ResponseWriter, req *http.Request) {
 	c := engine.pool.Get().(*Context)
 	c.writermem.reset(w)

logger.go

@@ -38,10 +38,14 @@ func ErrorLoggerT(typ ErrorType) HandlerFunc {
 	}
 }
 
+// Instances a Logger middleware that will write the logs to gin.DefaultWriter
+// By default gin.DefaultWriter = os.Stdout
 func Logger() HandlerFunc {
 	return LoggerWithWriter(DefaultWriter)
 }
 
+// Instance a Logger middleware with the specified writter buffer.
+// Example: os.Stdout, a file opened in write mode, a socket...
 func LoggerWithWriter(out io.Writer) HandlerFunc {
 	return func(c *Context) {
 		// Start timer