Merge pull request #400 from fuxiaohei/master

add api comments

app.go

@@ -10,19 +10,22 @@ import (
 	"github.com/astaxie/beego/context"
 )
 
+// FilterFunc defines filter function type.
 type FilterFunc func(*context.Context)
 
+// App defines beego application with a new PatternServeMux.
 type App struct {
 	Handlers *ControllerRegistor
 }
 
-// New returns a new PatternServeMux.
+// NewApp returns a new beego application.
 func NewApp() *App {
 	cr := NewControllerRegistor()
 	app := &App{Handlers: cr}
 	return app
 }
 
+// Run beego application.
 func (app *App) Run() {
 	addr := HttpAddr
 
@@ -84,39 +87,77 @@ func (app *App) Run() {
 	}
 }
 
+// Router adds a url-patterned controller handler.
+// The path argument supports regex rules and specific placeholders.
+// The c argument needs a controller handler implemented beego.ControllerInterface.
+// The mapping methods argument only need one string to define custom router rules.
+// usage:
+//	simple router
+// 	beego.Router("/admin", &admin.UserController{})
+//	beego.Router("/admin/index", &admin.ArticleController{})
+//
+// 	regex router
+//
+//	beego.Router(“/api/:id([0-9]+)“, &controllers.RController{})
+//
+//  custom rules
+//	beego.Router("/api/list",&RestController{},"*:ListFood")
+//	beego.Router("/api/create",&RestController{},"post:CreateFood")
+//	beego.Router("/api/update",&RestController{},"put:UpdateFood")
+//	beego.Router("/api/delete",&RestController{},"delete:DeleteFood")
 func (app *App) Router(path string, c ControllerInterface, mappingMethods ...string) *App {
 	app.Handlers.Add(path, c, mappingMethods...)
 	return app
 }
 
+// AutoRouter adds beego-defined controller handler.
+// if beego.AddAuto(&MainContorlller{}) and MainController has methods List and Page,
+// visit the url /main/list to exec List function or /main/page to exec Page function.
 func (app *App) AutoRouter(c ControllerInterface) *App {
 	app.Handlers.AddAuto(c)
 	return app
 }
 
+// UrlFor does another controller handler with params in current context.
+// The endpoint is formed as path.controller.name to defined the controller method which will run.
+// The values need key-pair data to assign into controller method.
 func (app *App) UrlFor(endpoint string, values ...string) string {
 	return app.Handlers.UrlFor(endpoint, values...)
 }
+
+// [Deprecated] use InsertFilter.
+// Filter adds a FilterFunc under pattern condition and named action.
+// The actions contains BeforeRouter,AfterStatic,BeforeExec,AfterExec and FinishRouter.
 func (app *App) Filter(pattern, action string, filter FilterFunc) *App {
 	app.Handlers.AddFilter(pattern, action, filter)
 	return app
 }
 
+// InsertFilter adds a FilterFunc with pattern condition and action constant.
+// The pos means action constant including
+// beego.BeforeRouter, beego.AfterStatic, beego.BeforeExec, beego.AfterExec and beego.FinishRouter.
 func (app *App) InsertFilter(pattern string, pos int, filter FilterFunc) *App {
 	app.Handlers.InsertFilter(pattern, pos, filter)
 	return app
 }
 
+// SetViewsPath sets view directory path in beego application.
+// it returns beego application self.
 func (app *App) SetViewsPath(path string) *App {
 	ViewsPath = path
 	return app
 }
 
+// SetStaticPath sets static directory path and proper url pattern in beego application.
+// if beego.SetStaticPath("static","public"), visit /static/* to load static file in folder "public".
+// it returns beego application self.
 func (app *App) SetStaticPath(url string, path string) *App {
 	StaticDir[url] = path
 	return app
 }
 
+// DelStaticPath removes the static folder setting in this url pattern in beego application.
+// it returns beego application self.
 func (app *App) DelStaticPath(url string) *App {
 	delete(StaticDir, url)
 	return app

beego.go

@@ -10,34 +10,50 @@ import (
 	"github.com/astaxie/beego/session"
 )
 
+// beego web framework version.
 const VERSION = "1.0.0"
 
+// Router adds a patterned controller handler to BeeApp.
+// it's an alias method of App.Router.
 func Router(rootpath string, c ControllerInterface, mappingMethods ...string) *App {
 	BeeApp.Router(rootpath, c, mappingMethods...)
 	return BeeApp
 }
 
+// RESTRouter adds a restful controller handler to BeeApp.
+// its' controller implements beego.ControllerInterface and
+// defines a param "pattern/:objectId" to visit each resource.
 func RESTRouter(rootpath string, c ControllerInterface) *App {
 	Router(rootpath, c)
 	Router(path.Join(rootpath, ":objectId"), c)
 	return BeeApp
 }
 
+// AutoRouter adds defined controller handler to BeeApp.
+// it's same to App.AutoRouter.
 func AutoRouter(c ControllerInterface) *App {
 	BeeApp.AutoRouter(c)
 	return BeeApp
 }
 
+// ErrorHandler registers http.HandlerFunc to each http err code string.
+// usage:
+// 	beego.ErrorHandler("404",NotFound)
+//	beego.ErrorHandler("500",InternalServerError)
 func Errorhandler(err string, h http.HandlerFunc) *App {
 	middleware.Errorhandler(err, h)
 	return BeeApp
 }
 
+// SetViewsPath sets view directory to BeeApp.
+// it's alias of App.SetViewsPath.
 func SetViewsPath(path string) *App {
 	BeeApp.SetViewsPath(path)
 	return BeeApp
 }
 
+// SetStaticPath sets static directory and url prefix to BeeApp.
+// it's alias of App.SetStaticPath.
 func SetStaticPath(url string, path string) *App {
 	if !strings.HasPrefix(url, "/") {
 		url = "/" + url
@@ -46,27 +62,33 @@ func SetStaticPath(url string, path string) *App {
 	return BeeApp
 }
 
+// DelStaticPath removes the static folder setting in this url pattern in beego application.
+// it's alias of App.DelStaticPath.
 func DelStaticPath(url string) *App {
 	delete(StaticDir, url)
 	return BeeApp
 }
 
-//!!DEPRECATED!! use InsertFilter
-//action has four values:
-//BeforRouter
-//AfterStatic
-//BeforExec
-//AfterExec
+// [Deprecated] use InsertFilter.
+// Filter adds a FilterFunc under pattern condition and named action.
+// The actions contains BeforeRouter,AfterStatic,BeforeExec,AfterExec and FinishRouter.
+// it's alias of App.Filter.
 func AddFilter(pattern, action string, filter FilterFunc) *App {
 	BeeApp.Filter(pattern, action, filter)
 	return BeeApp
 }
 
+// InsertFilter adds a FilterFunc with pattern condition and action constant.
+// The pos means action constant including
+// beego.BeforeRouter, beego.AfterStatic, beego.BeforeExec, beego.AfterExec and beego.FinishRouter.
+// it's alias of App.InsertFilter.
 func InsertFilter(pattern string, pos int, filter FilterFunc) *App {
 	BeeApp.InsertFilter(pattern, pos, filter)
 	return BeeApp
 }
 
+// Run beego application.
+// it's alias of App.Run.
 func Run() {
 	// if AppConfigPath not In the conf/app.conf reParse config
 	if AppConfigPath != filepath.Join(AppPath, "conf", "app.conf") {

config.go

@@ -14,54 +14,53 @@ import (
 )
 
 var (
-	BeeApp                 *App
+	BeeApp                 *App // beego application
 	AppName                string
 	AppPath                string
 	AppConfigPath          string
 	StaticDir              map[string]string
-	TemplateCache          map[string]*template.Template
-	StaticExtensionsToGzip []string //Files which should also be compressed with gzip (.js, .css, etc)
+	TemplateCache          map[string]*template.Template // template caching map
+	StaticExtensionsToGzip []string                      // files with should be compressed with gzip (.js,.css,etc)
 	HttpAddr               string
 	HttpPort               int
 	HttpTLS                bool
 	HttpCertFile           string
 	HttpKeyFile            string
-	RecoverPanic           bool
-	AutoRender             bool
+	RecoverPanic           bool // flag of auto recover panic
+	AutoRender             bool // flag of render template automatically
 	ViewsPath              string
-	RunMode                string //"dev" or "prod"
+	RunMode                string // run mode, "dev" or "prod"
 	AppConfig              config.ConfigContainer
-	//related to session
-	GlobalSessions        *session.Manager //GlobalSessions
-	SessionOn             bool             // whether auto start session,default is false
-	SessionProvider       string           // default session provider  memory mysql redis
-	SessionName           string           // sessionName cookie's name
-	SessionGCMaxLifetime  int64            // session's gc maxlifetime
-	SessionSavePath       string           // session savepath if use mysql/redis/file this set to the connectinfo
-	SessionHashFunc       string
-	SessionHashKey        string
-	SessionCookieLifeTime int
+	GlobalSessions         *session.Manager // global session mananger
+	SessionOn              bool             // flag of starting session auto. default is false.
+	SessionProvider        string           // default session provider, memory, mysql , redis ,etc.
+	SessionName            string           // the cookie name when saving session id into cookie.
+	SessionGCMaxLifetime   int64            // session gc time for auto cleaning expired session.
+	SessionSavePath        string           // if use mysql/redis/file provider, define save path to connection info.
+	SessionHashFunc        string           // session hash generation func.
+	SessionHashKey         string           // session hash salt string.
+	SessionCookieLifeTime  int              // the life time of session id in cookie.
 	UseFcgi                bool
 	MaxMemory              int64
-	EnableGzip            bool   // enable gzip
-	DirectoryIndex        bool   //enable DirectoryIndex default is false
-	EnableHotUpdate       bool   //enable HotUpdate default is false
-	HttpServerTimeOut     int64  //set httpserver timeout
-	ErrorsShow            bool   //set weather show errors
-	XSRFKEY               string //set XSRF
-	EnableXSRF            bool
-	XSRFExpire            int
-	CopyRequestBody       bool //When in raw application, You want to the reqeustbody
+	EnableGzip             bool // flag of enable gzip
+	DirectoryIndex         bool // flag of display directory index. default is false.
+	EnableHotUpdate        bool // flag of hot update checking by app self. default is false.
+	HttpServerTimeOut      int64
+	ErrorsShow             bool   // flag of show errors in page. if true, show error and trace info in page rendered with error template.
+	XSRFKEY                string // xsrf hash salt string.
+	EnableXSRF             bool   // flag of enable xsrf.
+	XSRFExpire             int    // the expiry of xsrf value.
+	CopyRequestBody        bool   // flag of copy raw request body in context.
 	TemplateLeft           string
 	TemplateRight          string
-	BeegoServerName       string
-	EnableAdmin           bool   //enable admin module to log api time
-	AdminHttpAddr         string //admin module http addr
+	BeegoServerName        string // beego server name exported in response header.
+	EnableAdmin            bool   // flag of enable admin module to log every request info.
+	AdminHttpAddr          string // http server configurations for admin module.
 	AdminHttpPort          int
 )
 
 func init() {
-	// create beeapp
+	// create beego application
 	BeeApp = NewApp()
 
 	// initialize default configurations
@@ -135,7 +134,8 @@ func init() {
 	}
 }
 
-//parse config now only support ini, next will support json
+// ParseConfig parsed default config file.
+// now only support ini, next will support json.
 func ParseConfig() (err error) {
 	AppConfig, err = config.NewConfig("ini", AppConfigPath)
 	if err != nil {

filter.go

@@ -5,6 +5,8 @@ import (
 	"strings"
 )
 
+// FilterRouter defines filter operation before controller handler execution.
+// it can match patterned url and do filter function when action arrives.
 type FilterRouter struct {
 	pattern     string
 	regex       *regexp.Regexp
@@ -14,6 +16,8 @@ type FilterRouter struct {
 	parseParams map[string]string
 }
 
+// ValidRouter check current request is valid for this filter.
+// if matched, returns parsed params in this request by defined filter router pattern.
 func (mr *FilterRouter) ValidRouter(router string) (bool, map[string]string) {
 	if mr.pattern == "" {
 		return true, nil

flash.go

@@ -6,18 +6,22 @@ import (
 	"strings"
 )
 
+// the separation string when encoding flash data.
 const BEEGO_FLASH_SEP = "#BEEGOFLASH#"
 
+// FlashData is a tools to maintain data when using across request.
 type FlashData struct {
 	Data map[string]string
 }
 
+// NewFlash return a new empty FlashData struct.
 func NewFlash() *FlashData {
 	return &FlashData{
 		Data: make(map[string]string),
 	}
 }
 
+// Notice writes notice message to flash.
 func (fd *FlashData) Notice(msg string, args ...interface{}) {
 	if len(args) == 0 {
 		fd.Data["notice"] = msg
@@ -26,6 +30,7 @@ func (fd *FlashData) Notice(msg string, args ...interface{}) {
 	}
 }
 
+// Warning writes warning message to flash.
 func (fd *FlashData) Warning(msg string, args ...interface{}) {
 	if len(args) == 0 {
 		fd.Data["warning"] = msg
@@ -34,6 +39,7 @@ func (fd *FlashData) Warning(msg string, args ...interface{}) {
 	}
 }
 
+// Error writes error message to flash.
 func (fd *FlashData) Error(msg string, args ...interface{}) {
 	if len(args) == 0 {
 		fd.Data["error"] = msg
@@ -42,6 +48,8 @@ func (fd *FlashData) Error(msg string, args ...interface{}) {
 	}
 }
 
+// Store does the saving operation of flash data.
+// the data are encoded and saved in cookie.
 func (fd *FlashData) Store(c *Controller) {
 	c.Data["flash"] = fd.Data
 	var flashValue string
@@ -51,6 +59,7 @@ func (fd *FlashData) Store(c *Controller) {
 	c.Ctx.SetCookie("BEEGO_FLASH", url.QueryEscape(flashValue), 0, "/")
 }
 
+// ReadFromRequest parsed flash data from encoded values in cookie.
 func ReadFromRequest(c *Controller) *FlashData {
 	flash := &FlashData{
 		Data: make(map[string]string),