From 48633f7001632314d69334412bfba7637b74f7e3 Mon Sep 17 00:00:00 2001 From: Manu Mtz-Almeida Date: Fri, 29 May 2015 21:03:41 +0200 Subject: [PATCH] Better documentation --- context.go | 6 +++--- errors.go | 14 ++++++++++++++ fs.go | 6 ++++++ gin.go | 15 ++++++++++++++- logger.go | 4 ++++ 5 files changed, 41 insertions(+), 4 deletions(-) diff --git a/context.go b/context.go index 07a90179..7473d3d2 100644 --- a/context.go +++ b/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) } diff --git a/errors.go b/errors.go index b395c93a..607a583b 100644 --- a/errors.go +++ b/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{} diff --git a/fs.go b/fs.go index 6f09df74..f95dc84a 100644 --- a/fs.go +++ b/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 diff --git a/gin.go b/gin.go index 83e3a063..adb734b3 100644 --- a/gin.go +++ b/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) diff --git a/logger.go b/logger.go index 1684d0b8..788fb01b 100644 --- a/logger.go +++ b/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