Add comments for BConfig

server/web/config.go

@@ -35,96 +35,400 @@ import (
 // Config is the main struct for BConfig
 // TODO after supporting multiple servers, remove common config to somewhere else
 type Config struct {
+	// AppName
+	// @Description Application's name. You'd better set it because we use it to do some logging and tracing
+	// @Default beego
 	AppName             string // Application name
+	// RunMode
+	// @Description it's the same as environment. In general, we have different run modes.
+	// For example, the most common case is using dev, test, prod three environments
+	// when you are developing the application, you should set it as dev
+	// when you completed coding and want QA to test your code, you should deploy your application to test environment
+	// and the RunMode should be set as test
+	// when you completed all tests, you want to deploy it to prod, you should set it to prod
+	// You should never set RunMode="dev" when you deploy the application to prod
+	// because Beego will do more things which need Go SDK and other tools when it found out the RunMode="dev"
+	// @Default dev
 	RunMode             string // Running Mode: dev | prod
+
+	// RouterCaseSensitive
+	// @Description If it was true, it means that the router is case sensitive.
+	// For example, when you register a router with pattern "/hello",
+	// 1. If this is true, and the request URL is "/Hello", it won't match this pattern
+	// 2. If this is false and the request URL is "/Hello", it will match this pattern
+	// @Default true
 	RouterCaseSensitive bool
+	// RecoverPanic
+	// @Description if it was true, Beego will try to recover from panic when it serves your http request
+	// So you should notice that it doesn't mean that Beego will recover all panic cases.
+	// @Default true
 	RecoverPanic        bool
+	// CopyRequestBody
+	// @Description if it's true, Beego will copy the request body. But if the request body's size > MaxMemory,
+	// Beego will return 413 as http status
+	// If you are building RESTful API, please set it to true.
+	// And if you want to read data from request Body multiple times, please set it to true
+	// In general, if you don't meet any performance issue, you could set it to true
+	// @Default false
 	CopyRequestBody     bool
+	// EnableGzip
+	// @Description If it was true, Beego will try to compress data by using zip algorithm.
+	// But there are two points:
+	// 1. Only static resources will be compressed
+	// 2. Only those static resource which has the extension specified by StaticExtensionsToGzip will be compressed
+	// @Default false
 	EnableGzip          bool
+	// EnableErrorsShow
+	// @Description If it's true, Beego will show error message to page
+	// it will work with ErrorMaps which allows you register some error handler
+	// You may want to set it to false when application was deploy to prod environment
+	// because you may not want to expose your internal error msg to your users
+	// it's a little bit unsafe
+	// @Default true
 	EnableErrorsShow    bool
+	// EnableErrorsRender
+	// @Description If it's true, it will output the error msg as a page. It's similar to EnableErrorsShow
+	// And this configure item only work in dev run mode (see RunMode)
+	// @Default true
 	EnableErrorsRender  bool
+	// ServerName
+	// @Description server name. For example, in large scale system,
+	// you may want to deploy your application to several machines, so that each of them has a server name
+	// we suggest you'd better set value because Beego use this to output some DEBUG msg,
+	// or integrated with other tools such as tracing, metrics
+	// @Default
 	ServerName          string
+
+	// RecoverFunc
+	// @Description when Beego want to recover from panic, it will use this func as callback
+	// see RecoverPanic
+	// @Default defaultRecoverPanic
 	RecoverFunc         func(*context.Context, *Config)
-	// MaxMemory and MaxUploadSize are used to limit the request body
+	// @Description MaxMemory and MaxUploadSize are used to limit the request body
 	// if the request is not uploading file, MaxMemory is the max size of request body
 	// if the request is uploading file, MaxUploadSize is the max size of request body
+	// if CopyRequestBody is true, this value will be used as the threshold of request body
+	// see CopyRequestBody
+	// the default value is 1 << 26 (64MB)
+	// @Default 67108864
 	MaxMemory     int64
+	// MaxUploadSize
+	// @Description  MaxMemory and MaxUploadSize are used to limit the request body
+	// if the request is not uploading file, MaxMemory is the max size of request body
+	// if the request is uploading file, MaxUploadSize is the max size of request body
+	// the default value is 1 << 30 (1GB)
+	// @Default 1073741824
 	MaxUploadSize int64
+	// Listen
+	// @Description the configuration about socket or http protocol
 	Listen        Listen
+	// WebConfig
+	// @Description the configuration about Web
 	WebConfig     WebConfig
+	// LogConfig
+	// @Description log configuration
 	Log           LogConfig
 }
 
 // Listen holds for http and https related config
 type Listen struct {
-	Graceful          bool // Graceful means use graceful module to start the server
+	// Graceful
+	// @Description means use graceful module to start the server
+	// @Default false
+	Graceful          bool
+	// ListenTCP4
+	// @Description if it's true, means that Beego only work for TCP4
+	// please check net.Listen function
+	// In general, you should not set it to true
+	// @Default false
 	ListenTCP4        bool
+	// EnableHTTP
+	// @Description if it's true, Beego will accept HTTP request.
+	// But if you want to use HTTPS only, please set it to false
+	// see EnableHTTPS
+	// @Default true
 	EnableHTTP        bool
+	// AutoTLS
+	// @Description If it's true, Beego will use default value to initialize the TLS configure
+	// But those values could be override if you have custom value.
+	// see Domains, TLSCacheDir
+	// @Default false
 	AutoTLS           bool
+	// EnableHTTPS
+	// @Description If it's true, Beego will accept HTTPS request.
+	// Now, you'd better use HTTPS protocol on prod environment to get better security
+	// In prod, the best option is EnableHTTPS=true and EnableHTTP=false
+	// see EnableHTTP
+	// @Default false
 	EnableHTTPS       bool
+	// EnableMutualHTTPS
+	// @Description if it's true, Beego will handle requests on incoming mutual TLS connections
+	// see Server.ListenAndServeMutualTLS
+	// @Default false
 	EnableMutualHTTPS bool
+	// EnableAdmin
+	// @Description if it's true, Beego will provide admin service.
+	// You can visit the admin service via browser.
+	// The default port is 8088
+	// see AdminPort
+	// @Default false
 	EnableAdmin       bool
+	// EnableFcgi
+	// @Description
+	// @Default false
 	EnableFcgi        bool
-	EnableStdIo       bool // EnableStdIo works with EnableFcgi Use FCGI via standard I/O
+	// EnableStdIo
+	// @Description EnableStdIo works with EnableFcgi Use FCGI via standard I/O
+	// @Default false
+	EnableStdIo       bool
+	// ServerTimeOut
+	// @Description Beego use this as ReadTimeout and WriteTimeout
+	// The unit is second.
+	// see http.Server.ReadTimeout, WriteTimeout
+	// @Default 0
 	ServerTimeOut     int64
+	// HTTPAddr
+	// @Description Beego listen to this address when the application start up.
+	// @Default ""
 	HTTPAddr          string
+	// HTTPPort
+	// @Description Beego listen to this port
+	// you'd better change this value when you deploy to prod environment
+	// @Default 8080
 	HTTPPort          int
+	// Domains
+	// @Description Beego use this to configure TLS. Those domains are "white list" domain
+	// @Default []
 	Domains           []string
+	// TLSCacheDir
+	// @Description Beego use this as cache dir to store TLS cert data
+	// @Default ""
 	TLSCacheDir       string
+	// HTTPSAddr
+	// @Description Beego will listen to this address to accept HTTPS request
+	// see EnableHTTPS
+	// @Default ""
 	HTTPSAddr         string
+	// HTTPSPort
+	// @Description  Beego will listen to this port to accept HTTPS request
+	// @Default 10443
 	HTTPSPort         int
+	// HTTPSCertFile
+	// @Description Beego read this file as cert file
+	// When you are using HTTPS protocol, please configure it
+	// see HTTPSKeyFile
+	// @Default ""
 	HTTPSCertFile     string
+	// HTTPSKeyFile
+	// @Description Beego read this file as key file
+	// When you are using HTTPS protocol, please configure it
+	// see HTTPSCertFile
+	// @Default ""
 	HTTPSKeyFile      string
+	// TrustCaFile
+	// @Description Beego read this file as CA file
+	// @Default ""
 	TrustCaFile       string
+	// AdminAddr
+	// @Description Beego will listen to this address to provide admin service
+	// In general, it should be the same with your application address, HTTPAddr or HTTPSAddr
+	// @Default ""
 	AdminAddr         string
+	// AdminPort
+	// @Description  Beego will listen to this port to provide admin service
+	// @Default 8088
 	AdminPort         int
+	// @Description Beego use this tls.ClientAuthType to initialize TLS connection
+	// The default value is tls.RequireAndVerifyClientCert
+	// @Default 4
 	ClientAuth        int
 }
 
 // WebConfig holds web related config
 type WebConfig struct {
+	// AutoRender
+	// @Description If it's true, Beego will render the page based on your template and data
+	// In general, keep it as true.
+	// But if you are building RESTFul API and you don't have any page,
+	// you can set it to false
+	// @Default true
 	AutoRender             bool
+	// Deprecated: Beego didn't use it anymore
 	EnableDocs             bool
+	// EnableXSRF
+	// @Description If it's true, Beego will help to provide XSRF support
+	// But you should notice that, now Beego only work for HTTPS protocol with XSRF
+	// because it's not safe if using HTTP protocol
+	// And, the cookie storing XSRF token has two more flags HttpOnly and Secure
+	// It means that you must use HTTPS protocol and you can not read the token from JS script
+	// This is completed different from Beego 1.x because we got many security reports
+	// And if you are in dev environment, you could set it to false
+	// @Default false
 	EnableXSRF             bool
+	// DirectoryIndex
+	// @Description When Beego serves static resources request, it will look up the file.
+	// If the file is directory, Beego will try to find the index.html as the response
+	// But if the index.html is not exist or it's a directory,
+	// Beego will return 403 response if DirectoryIndex is **false**
+	// @Default false
 	DirectoryIndex         bool
+	// FlashName
+	// @Description the cookie's name when Beego try to store the flash data into cookie
+	// @Default BEEGO_FLASH
 	FlashName              string
+	// FlashSeparator
+	// @Description When Beego read flash data from request, it uses this as the separator
+	// @Default BEEGOFLASH
 	FlashSeparator         string
+	// StaticDir
+	// @Description Beego uses this as static resources' root directory.
+	// It means that Beego will try to search static resource from this start point
+	// It's a map, the key is the path and the value is the directory
+	// For example, the default value is /static => static,
+	// which means that when Beego got a request with path /static/xxx
+	// Beego will try to find the resource from static directory
+	// @Default /static => static
 	StaticDir              map[string]string
+	// StaticExtensionsToGzip
+	// @Description The static resources with those extension wille be compressed if EnableGzip is true
+	// @Default [".css", ".js" ]
 	StaticExtensionsToGzip []string
+	// StaticCacheFileSize
+	// @Description If the size of static resource < StaticCacheFileSize, Beego will try to handle it by itself,
+	// it means that Beego will compressed the file data (if enable) and cache this file.
+	// But if the file size > StaticCacheFileSize, Beego just simply delegate the request to http.ServeFile
+	// the default value is 100KB.
+	// the max memory size of caching static files is StaticCacheFileSize * StaticCacheFileNum
+	// see StaticCacheFileNum
+	// @Default 102400
 	StaticCacheFileSize    int
+	// StaticCacheFileNum
+	// @Description Beego use it to control the memory usage of caching static resource file
+	// If the caching files > StaticCacheFileNum, Beego use LRU algorithm to remove caching file
+	// the max memory size of caching static files is StaticCacheFileSize * StaticCacheFileNum
+	// see StaticCacheFileSize
+	// @Default 1000
 	StaticCacheFileNum     int
+	// TemplateLeft
+	// @Description Beego use this to render page
+	// see TemplateRight
+	// @Default {{
 	TemplateLeft           string
+	// TemplateRight
+	// @Description Beego use this to render page
+	// see TemplateLeft
+	// @Default }}
 	TemplateRight          string
+	// ViewsPath
+	// @Description The directory of Beego application storing template
+	// @Default views
 	ViewsPath              string
+	// CommentRouterPath
+	// @Description Beego scans this directory and its sub directory to generate router
+	// Beego only scans this directory when it's in dev environment
+	// @Default controllers
 	CommentRouterPath      string
+	// XSRFKey
+	// @Description the name of cookie storing XSRF token
+	// see EnableXSRF
+	// @Default beegoxsrf
 	XSRFKey                string
+	// XSRFExpire
+	// @Description the expiration time of XSRF token cookie
+	// second
+	// @Default 0
 	XSRFExpire             int
+	// @Description session related config
 	Session                SessionConfig
 }
 
 // SessionConfig holds session related config
 type SessionConfig struct {
+	// SessionOn
+	// @Description if it's true, Beego will auto manage session
+	// @Default false
 	SessionOn                    bool
+	// SessionAutoSetCookie
+	// @Description if it's true, Beego will put the session token into cookie too
+	// @Default true
 	SessionAutoSetCookie         bool
-	SessionDisableHTTPOnly       bool // used to allow for cross domain cookies/javascript cookies.
+	// SessionDisableHTTPOnly
-	SessionEnableSidInHTTPHeader bool // enable store/get the sessionId into/from http headers
+	// @Description used to allow for cross domain cookies/javascript cookies
-	SessionEnableSidInURLQuery   bool // enable get the sessionId from Url Query params
+	// In general, you should not set it to true unless you understand the risk
+	// @Default false
+	SessionDisableHTTPOnly       bool
+	// SessionEnableSidInHTTPHeader
+	// @Description enable store/get the sessionId into/from http headers
+	// @Default false
+	SessionEnableSidInHTTPHeader bool
+	// SessionEnableSidInURLQuery
+	// @Description enable get the sessionId from Url Query params
+	// @Default false
+	SessionEnableSidInURLQuery   bool
+	// SessionProvider
+	// @Description session provider's name.
+	// You should confirm that this provider has been register via session.Register method
+	// the default value is memory. This is not suitable for distributed system
+	// @Default memory
 	SessionProvider              string
+	// SessionName
+	// @Description If SessionAutoSetCookie is true, we use this value as the cookie's name
+	// @Default beegosessionID
 	SessionName                  string
+	// SessionGCMaxLifetime
+	// @Description Beego will GC session to clean useless session.
+	// unit: second
+	// @Default 3600
 	SessionGCMaxLifetime         int64
+	// SessionProviderConfig
+	// @Description the config of session provider
+	// see SessionProvider
+	// you should read the document of session provider to learn how to set this value
+	// @Default ""
 	SessionProviderConfig        string
+	// SessionCookieLifeTime
+	// @Description If SessionAutoSetCookie is true,
+	// we use this value as the expiration time and max age of the cookie
+	// unit second
+	// @Default 0
 	SessionCookieLifeTime        int
+	// SessionDomain
+	// @Description If SessionAutoSetCookie is true, we use this value as the cookie's domain
+	// @Default ""
 	SessionDomain                string
+	// SessionNameInHTTPHeader
+	// @Description if SessionEnableSidInHTTPHeader is true, this value will be used as the http header
+	// @Default Beegosessionid
 	SessionNameInHTTPHeader      string
+	// SessionCookieSameSite
+	// @Description If SessionAutoSetCookie is true, we use this value as the cookie's same site policy
+	// the default value is http.SameSiteDefaultMode
+	// @Default 1
 	SessionCookieSameSite        http.SameSite
 }
 
 // LogConfig holds Log related config
 type LogConfig struct {
+	// AccessLogs
+	// @Description If it's true, Beego will log the HTTP request info
+	// @Default false
 	AccessLogs       bool
-	EnableStaticLogs bool // log static files requests default: false
+	// EnableStaticLogs
+	// @Description log static files requests
+	// @Default false
+	EnableStaticLogs bool
+	// FileLineNum
+	// @Description if it's true, it will log the line number
+	// @Default true
 	FileLineNum      bool
-	AccessLogsFormat string            // access log format: JSON_FORMAT, APACHE_FORMAT or empty string
+	// AccessLogsFormat
+	// @Description access log format: JSON_FORMAT, APACHE_FORMAT or empty string
+	// @Default APACHE_FORMAT
+	AccessLogsFormat string
+	// Outputs
+	// @Description the destination of access log
+	// the key is log adapter and the value is adapter's configure
+	// @Default "console" => ""
 	Outputs          map[string]string // Store Adaptor : config
 }
 

server/web/config_test.go

@@ -32,6 +32,10 @@ func TestDefaults(t *testing.T) {
 	}
 }
 
+func TestLoadAppConfig(t *testing.T) {
+	println(1 << 30)
+}
+
 func TestAssignConfig_01(t *testing.T) {
 	_BConfig := &Config{}
 	_BConfig.AppName = "beego_test"