add api comments in file config.go, controller.go, filter.go and flash.go

傅小黑
Showing 4 changed files with 126 additions and 31 deletions
config.go
controller.go
filter.go
flash.go
--- a/config.go
View file @b459cf2
+++ b/config.go
View file @b459cf2
@@ -14,54 +14,81 @@ import (
 )
 var (
+	// beego application
 	BeeApp                 *App
+	// application configurations
 	AppName                string
 	AppPath                string
 	AppConfigPath          string
 	StaticDir              map[string]string
+	// template caching map
 	TemplateCache          map[string]*template.Template
-	StaticExtensionsToGzip []string //Files which should also be compressed with gzip (.js, .css, etc)
+	// files with should be compressed with gzip (.js,.css,etc)
+	StaticExtensionsToGzip []string
+	// http server configurations
 	HttpAddr               string
 	HttpPort               int
 	HttpTLS                bool
 	HttpCertFile           string
 	HttpKeyFile            string
+	// flag of auto recover panic
 	RecoverPanic           bool
+	// flag of render template automatically
 	AutoRender             bool
 	ViewsPath              string
-	RunMode                string //"dev" or "prod"
+	// run mode, "dev" or "prod"
+	RunMode                string
 	AppConfig              config.ConfigContainer
-	//related to session
+	// global session mananger
-	GlobalSessions        *session.Manager //GlobalSessions
+	GlobalSessions        *session.Manager
-	SessionOn             bool             // whether auto start session,default is false
+	// flag of starting session auto. default is false.
-	SessionProvider       string           // default session provider  memory mysql redis
+	SessionOn             bool
-	SessionName           string           // sessionName cookie's name
+	// default session provider, memory, mysql , redis ,etc.
-	SessionGCMaxLifetime  int64            // session's gc maxlifetime
+	SessionProvider       string
-	SessionSavePath       string           // session savepath if use mysql/redis/file this set to the connectinfo
+	// the cookie name when saving session id into cookie.
+	SessionName           string
+	// session gc time for auto cleaning expired session.
+	SessionGCMaxLifetime  int64
+	// if use mysql/redis/file provider, define save path to connection info.
+	SessionSavePath       string
+	// session hash generation func.
 	SessionHashFunc       string
+	// session hash salt string.
 	SessionHashKey        string
+	// the life time of session id in cookie.
 	SessionCookieLifeTime int
 	UseFcgi               bool
 	MaxMemory             int64
-	EnableGzip            bool   // enable gzip
+	// flag of enable gzip
-	DirectoryIndex        bool   //enable DirectoryIndex default is false
+	EnableGzip            bool
-	EnableHotUpdate       bool   //enable HotUpdate default is false
+	// flag of display directory index. default is false.
-	HttpServerTimeOut     int64  //set httpserver timeout
+	DirectoryIndex        bool
-	ErrorsShow            bool   //set weather show errors
+	// flag of hot update checking in app self. default is false.
-	XSRFKEY               string //set XSRF
+	EnableHotUpdate       bool
+	HttpServerTimeOut     int64
+	// flag of show errors in page. if true, show error and trace info in page rendered with error template.
+	ErrorsShow            bool
+	// xsrf hash salt string.
+	XSRFKEY               string
+	// flag of enable xsrf.
 	EnableXSRF            bool
+	// the expiry of xsrf value.
 	XSRFExpire            int
-	CopyRequestBody       bool //When in raw application, You want to the reqeustbody
+	// flag of copy raw request body in context.
+	CopyRequestBody       bool
 	TemplateLeft          string
 	TemplateRight         string
+	// beego server name exported in response header.
 	BeegoServerName       string
-	EnableAdmin           bool   //enable admin module to log api time
+	// flag of enable admin module to log every request info.
-	AdminHttpAddr         string //admin module http addr
+	EnableAdmin           bool
+	// http server configurations for admin module.
+	AdminHttpAddr         string
 	AdminHttpPort         int
 )
 func init() {
-	// create beeapp
+	// create beego application
 	BeeApp = NewApp()
 	// initialize default configurations
@@ -100,7 +127,7 @@ func init() {
 	UseFcgi = false
-	MaxMemory = 1 << 26 //64MB
+	MaxMemory = 1<<26 //64MB
 	EnableGzip = false
@@ -135,7 +162,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 {
--- a/controller.go
View file @b459cf2
+++ b/controller.go
View file @b459cf2
@@ -25,9 +25,12 @@ import (
 )
 var (
+	// custom error when user stop request handler manually.
 	USERSTOPRUN = errors.New("User stop run")
 )
+// Controller defines some basic http request handler operations, such as
+// http context, template and view, session and xsrf.
 type Controller struct {
 	Ctx            *context.Context
 	Data           map[interface{}]interface{}
@@ -43,6 +46,7 @@ type Controller struct {
 	AppController  interface{}
 }
+// ControllerInterface is an interface to uniform all controller handler.
 type ControllerInterface interface {
 	Init(ct *context.Context, controllerName, actionName string, app interface{})
 	Prepare()
@@ -59,6 +63,7 @@ type ControllerInterface interface {
 	CheckXsrfCookie() bool
 }
+// Init generates default values of controller operations.
 func (c *Controller) Init(ctx *context.Context, controllerName, actionName string, app interface{}) {
 	c.Data = make(map[interface{}]interface{})
 	c.Layout = ""
@@ -70,42 +75,52 @@ func (c *Controller) Init(ctx *context.Context, controllerName, actionName strin
 	c.AppController = app
 }
+// Prepare runs after Init before request function execution.
 func (c *Controller) Prepare() {
 }
+// Finish runs after request function execution.
 func (c *Controller) Finish() {
 }
+// Get adds a request function to handle GET request.
 func (c *Controller) Get() {
 	http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405)
 }
+// Post adds a request function to handle POST request.
 func (c *Controller) Post() {
 	http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405)
 }
+// Delete adds a request function to handle DELETE request.
 func (c *Controller) Delete() {
 	http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405)
 }
+// Put adds a request function to handle PUT request.
 func (c *Controller) Put() {
 	http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405)
 }
+// Head adds a request function to handle HEAD request.
 func (c *Controller) Head() {
 	http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405)
 }
+// Patch adds a request function to handle PATCH request.
 func (c *Controller) Patch() {
 	http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405)
 }
+// Options adds a request function to handle OPTIONS request.
 func (c *Controller) Options() {
 	http.Error(c.Ctx.ResponseWriter, "Method Not Allowed", 405)
 }
+// Render sends the response with rendered template bytes as text/html type.
 func (c *Controller) Render() error {
 	rb, err := c.RenderBytes()
@@ -118,24 +133,26 @@ func (c *Controller) Render() error {
 	return nil
 }
+// RenderString returns the rendered template string. Do not send out response.
 func (c *Controller) RenderString() (string, error) {
 	b, e := c.RenderBytes()
 	return string(b), e
 }
+// RenderBytes returns the bytes of renderd tempate string. Do not send out response.
 func (c *Controller) RenderBytes() ([]byte, error) {
 	//if the controller has set layout, then first get the tplname's content set the content to the layout
 	if c.Layout != "" {
 		if c.TplNames == "" {
-			c.TplNames = strings.ToLower(c.controllerName) + "/" + strings.ToLower(c.actionName) + "." + c.TplExt
+			c.TplNames = strings.ToLower(c.controllerName)+"/"+strings.ToLower(c.actionName)+"." + c.TplExt
 		}
 		if RunMode == "dev" {
 			BuildTemplate(ViewsPath)
 		}
 		newbytes := bytes.NewBufferString("")
 		if _, ok := BeeTemplates[c.TplNames]; !ok {
-			panic("can't find templatefile in the path:" + c.TplNames)
+			panic("can't find templatefile in the path:"+c.TplNames)
-			return []byte{}, errors.New("can't find templatefile in the path:" + c.TplNames)
+			return []byte{}, errors.New("can't find templatefile in the path:"+c.TplNames)
 		}
 		err := BeeTemplates[c.TplNames].ExecuteTemplate(newbytes, c.TplNames, c.Data)
 		if err != nil {
@@ -154,15 +171,15 @@ func (c *Controller) RenderBytes() ([]byte, error) {
 		return icontent, nil
 	} else {
 		if c.TplNames == "" {
-			c.TplNames = strings.ToLower(c.controllerName) + "/" + strings.ToLower(c.actionName) + "." + c.TplExt
+			c.TplNames = strings.ToLower(c.controllerName)+"/"+strings.ToLower(c.actionName)+"." + c.TplExt
 		}
 		if RunMode == "dev" {
 			BuildTemplate(ViewsPath)
 		}
 		ibytes := bytes.NewBufferString("")
 		if _, ok := BeeTemplates[c.TplNames]; !ok {
-			panic("can't find templatefile in the path:" + c.TplNames)
+			panic("can't find templatefile in the path:"+c.TplNames)
-			return []byte{}, errors.New("can't find templatefile in the path:" + c.TplNames)
+			return []byte{}, errors.New("can't find templatefile in the path:"+c.TplNames)
 		}
 		err := BeeTemplates[c.TplNames].ExecuteTemplate(ibytes, c.TplNames, c.Data)
 		if err != nil {
@@ -175,10 +192,12 @@ func (c *Controller) RenderBytes() ([]byte, error) {
 	return []byte{}, nil
 }
+// Redirect sends the redirection response to url with status code.
 func (c *Controller) Redirect(url string, code int) {
 	c.Ctx.Redirect(code, url)
 }
+// Aborts stops controller handler and show the error data if code is defined in ErrorMap or code string.
 func (c *Controller) Abort(code string) {
 	status, err := strconv.Atoi(code)
 	if err == nil {
@@ -188,21 +207,26 @@ func (c *Controller) Abort(code string) {
 	}
 }
+// StopRun makes panic of USERSTOPRUN error and go to recover function if defined.
 func (c *Controller) StopRun() {
 	panic(USERSTOPRUN)
 }
+// UrlFor does another controller handler in this request function.
+// it goes to this controller method if endpoint is not clear.
 func (c *Controller) UrlFor(endpoint string, values ...string) string {
 	if len(endpoint) <= 0 {
 		return ""
 	}
 	if endpoint[0] == '.' {
-		return UrlFor(reflect.Indirect(reflect.ValueOf(c.AppController)).Type().Name()+endpoint, values...)
+		return UrlFor(reflect.Indirect(reflect.ValueOf(c.AppController)).Type().Name() + endpoint, values...)
 	} else {
 		return UrlFor(endpoint, values...)
 	}
+	return ""
 }
+// ServeJson sends a json response with encoding charset.
 func (c *Controller) ServeJson(encoding ...bool) {
 	var hasIndent bool
 	var hasencoding bool
@@ -217,6 +241,7 @@ func (c *Controller) ServeJson(encoding ...bool) {
 	c.Ctx.Output.Json(c.Data["json"], hasIndent, hasencoding)
 }
+// ServeJson sends a jsonp response.
 func (c *Controller) ServeJsonp() {
 	var hasIndent bool
 	if RunMode == "prod" {
@@ -227,6 +252,7 @@ func (c *Controller) ServeJsonp() {
 	c.Ctx.Output.Jsonp(c.Data["jsonp"], hasIndent)
 }
+// ServeJson sends xml response.
 func (c *Controller) ServeXml() {
 	var hasIndent bool
 	if RunMode == "prod" {
@@ -237,6 +263,7 @@ func (c *Controller) ServeXml() {
 	c.Ctx.Output.Xml(c.Data["xml"], hasIndent)
 }
+// Input returns the input data map from POST or PUT request body and query string.
 func (c *Controller) Input() url.Values {
 	ct := c.Ctx.Request.Header.Get("Content-Type")
 	if strings.Contains(ct, "multipart/form-data") {
@@ -247,14 +274,18 @@ func (c *Controller) Input() url.Values {
 	return c.Ctx.Request.Form
 }
+// ParseForm maps input data map to obj struct.
 func (c *Controller) ParseForm(obj interface{}) error {
 	return ParseForm(c.Input(), obj)
 }
+// GetString returns the input value by key string.
 func (c *Controller) GetString(key string) string {
 	return c.Input().Get(key)
 }
+// GetStrings returns the input string slice by key string.
+// it's designed for multi-value input field such as checkbox(input[type=checkbox]), multi-selection.
 func (c *Controller) GetStrings(key string) []string {
 	r := c.Ctx.Request
 	if r.Form == nil {
@@ -267,29 +298,36 @@ func (c *Controller) GetStrings(key string) []string {
 	return []string{}
 }
+// GetInt returns input value as int64.
 func (c *Controller) GetInt(key string) (int64, error) {
 	return strconv.ParseInt(c.Input().Get(key), 10, 64)
 }
+// GetBool returns input value as bool.
 func (c *Controller) GetBool(key string) (bool, error) {
 	return strconv.ParseBool(c.Input().Get(key))
 }
+// GetFloat returns input value as float64.
 func (c *Controller) GetFloat(key string) (float64, error) {
 	return strconv.ParseFloat(c.Input().Get(key), 64)
 }
+// GetFile returns the file data in file upload field named as key.
+// it returns the first one of multi-uploaded files.
 func (c *Controller) GetFile(key string) (multipart.File, *multipart.FileHeader, error) {
 	return c.Ctx.Request.FormFile(key)
 }
+// SaveToFile saves uploaded file to new path.
+// it only operates the first one of mutil-upload form file field.
 func (c *Controller) SaveToFile(fromfile, tofile string) error {
 	file, _, err := c.Ctx.Request.FormFile(fromfile)
 	if err != nil {
 		return err
 	}
 	defer file.Close()
-	f, err := os.OpenFile(tofile, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0666)
+	f, err := os.OpenFile(tofile, os.O_WRONLY | os.O_CREATE | os.O_TRUNC, 0666)
 	if err != nil {
 		return err
 	}
@@ -298,6 +336,7 @@ func (c *Controller) SaveToFile(fromfile, tofile string) error {
 	return nil
 }
+// StartSession starts session and load old session data info this controller.
 func (c *Controller) StartSession() session.SessionStore {
 	if c.CruSession == nil {
 		c.CruSession = c.Ctx.Input.CruSession
@@ -305,6 +344,7 @@ func (c *Controller) StartSession() session.SessionStore {
 	return c.CruSession
 }
+// SetSession puts value into session.
 func (c *Controller) SetSession(name interface{}, value interface{}) {
 	if c.CruSession == nil {
 		c.StartSession()
@@ -312,6 +352,7 @@ func (c *Controller) SetSession(name interface{}, value interface{}) {
 	c.CruSession.Set(name, value)
 }
+// GetSession gets value from session.
 func (c *Controller) GetSession(name interface{}) interface{} {
 	if c.CruSession == nil {
 		c.StartSession()
@@ -319,6 +360,7 @@ func (c *Controller) GetSession(name interface{}) interface{} {
 	return c.CruSession.Get(name)
 }
+// SetSession removes value from session.
 func (c *Controller) DelSession(name interface{}) {
 	if c.CruSession == nil {
 		c.StartSession()
@@ -326,19 +368,24 @@ func (c *Controller) DelSession(name interface{}) {
 	c.CruSession.Delete(name)
 }
+// SessionRegenerateID regenerates session id for this session.
+// the session data have no changes.
 func (c *Controller) SessionRegenerateID() {
 	c.CruSession = GlobalSessions.SessionRegenerateId(c.Ctx.ResponseWriter, c.Ctx.Request)
 	c.Ctx.Input.CruSession = c.CruSession
 }
+// DestroySession cleans session data and session cookie.
 func (c *Controller) DestroySession() {
 	GlobalSessions.SessionDestroy(c.Ctx.ResponseWriter, c.Ctx.Request)
 }
+// IsAjax returns this request is ajax or not.
 func (c *Controller) IsAjax() bool {
 	return c.Ctx.Input.IsAjax()
 }
+// GetSecureCookie returns decoded cookie value from encoded browser cookie values.
 func (c *Controller) GetSecureCookie(Secret, key string) (string, bool) {
 	val := c.Ctx.GetCookie(key)
 	if val == "" {
@@ -365,6 +412,7 @@ func (c *Controller) GetSecureCookie(Secret, key string) (string, bool) {
 	return string(res), true
 }
+// SetSecureCookie puts value into cookie after encoded the value.
 func (c *Controller) SetSecureCookie(Secret, name, val string, age int64) {
 	vs := base64.URLEncoding.EncodeToString([]byte(val))
 	timestamp := strconv.FormatInt(time.Now().UnixNano(), 10)
@@ -375,6 +423,7 @@ func (c *Controller) SetSecureCookie(Secret, name, val string, age int64) {
 	c.Ctx.SetCookie(name, cookie, age, "/")
 }
+// XsrfToken creates a xsrf token string and returns.
 func (c *Controller) XsrfToken() string {
 	if c._xsrf_token == "" {
 		token, ok := c.GetSecureCookie(XSRFKEY, "_xsrf")
@@ -393,6 +442,9 @@ func (c *Controller) XsrfToken() string {
 	return c._xsrf_token
 }
+// CheckXsrfCookie checks xsrf token in this request is valid or not.
+// the token can provided in request header "X-Xsrftoken" and "X-CsrfToken"
+// or in form field value named as "_xsrf".
 func (c *Controller) CheckXsrfCookie() bool {
 	token := c.GetString("_xsrf")
 	if token == "" {
@@ -409,16 +461,18 @@ func (c *Controller) CheckXsrfCookie() bool {
 	return true
 }
+// XsrfFormHtml writes an input field contains xsrf token value.
 func (c *Controller) XsrfFormHtml() string {
 	return "<input type=\"hidden\" name=\"_xsrf\" value=\"" +
-		c._xsrf_token + "\"/>"
+			c._xsrf_token + "\"/>"
 }
+// GetControllerAndAction gets the executing controller name and action name.
 func (c *Controller) GetControllerAndAction() (controllerName, actionName string) {
 	return c.controllerName, c.actionName
 }
-//utils func for controller internal
+// getRandomString returns random string.
 func getRandomString(n int) string {
 	const alphanum = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
 	var bytes = make([]byte, n)
--- a/filter.go
View file @b459cf2
+++ b/filter.go
View file @b459cf2
@@ -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
--- a/flash.go
View file @b459cf2
+++ b/flash.go
View file @b459cf2
@@ -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),