config: updated docstrings in .ini files

configs/development.ini

@@ -45,10 +45,9 b' debug = true'
 host = 127.0.0.1
 port = 5000
 
-##################################
-##     WAITRESS WSGI SERVER     ##
-## Recommended for Development  ##
-##################################
+###########################################################
+## WAITRESS WSGI SERVER - Recommended for Development  ####
+###########################################################
 
 use = egg:waitress#main
 ## number of worker threads
@@ -66,15 +65,15 b' asyncore_use_poll = true'
 ## run with gunicorn --log-config rhodecode.ini --paste rhodecode.ini
 
 #use = egg:gunicorn#main
-## Sets the number of process workers. You must set `instance_id = *`
-## when this option is set to more than one worker, recommended
-## value is (2 * NUMBER_OF_CPUS + 1), eg 2CPU = 5 workers
-## The `instance_id = *` must be set in the [app:main] section below
+## Sets the number of process workers. More workers means more concurent connections
+## RhodeCode can handle at the same time. Each additional worker also it increases
+## memory usage as each has it's own set of caches.
+## Recommended value is (2 * NUMBER_OF_CPUS + 1), eg 2CPU = 5 workers, but no more
+## than 8-10 unless for really big deployments .e.g 700-1000 users.
+## `instance_id = *` must be set in the [app:main] section below (which is the default)
+## when using more than 1 worker.
 #workers = 2
-## number of threads for each of the worker, must be set to 1 for gevent
-## generally recommended to be at 1
-#threads = 1
-## process name
+## process name visible in process list
 #proc_name = rhodecode
 ## type of worker class, one of sync, gevent
 ## recommended for bigger setup is using of of other than sync one
@@ -152,12 +151,12 b' gzip_responses = false'
 ## autogenerate javascript routes file on startup
 generate_js_files = false
 
-## Optional Languages
-## en(default), be, de, es, fr, it, ja, pl, pt, ru, zh
+## System global default language.
+## All available languages: en(default), be, de, es, fr, it, ja, pl, pt, ru, zh
 lang = en
 
-## perform a full repository scan on each server start, this should be
-## set to false after first startup, to allow faster server restarts.
+## Perform a full repository scan and import on each server start.
+## Settings this to true could lead to very long startup time.
 startup.import_repos = false
 
 ## Uncomment and set this path to use archive download cache.
@@ -171,23 +170,23 b' startup.import_repos = false'
 ## SSH calls. Set this for events to receive proper url for SSH calls.
 app.base_url = http://rhodecode.local
 
-## change this to unique ID for security
+## Unique application ID. Should be a random unique string for security.
 app_instance_uuid = rc-production
 
-## cut off limit for large diffs (size in bytes). If overall diff size on
+## Cut off limit for large diffs (size in bytes). If overall diff size on
 ## commit, or pull request exceeds this limit this diff will be displayed
 ## partially. E.g 512000 == 512Kb
 cut_off_limit_diff = 512000
 
-## cut off limit for large files inside diffs (size in bytes). Each individual
+## Cut off limit for large files inside diffs (size in bytes). Each individual
 ## file inside diff which exceeds this limit will be displayed partially.
 ##  E.g 128000 == 128Kb
 cut_off_limit_file = 128000
 
-## use cache version of scm repo everywhere
+## use cached version of vcs repositories everywhere. Recommended to be `true`
 vcs_full_cache = true
 
-## force https in RhodeCode, fixes https redirects, assumes it's always https
+## Force https in RhodeCode, fixes https redirects, assumes it's always https.
 ## Normally this is controlled by proper http flags sent from http server
 force_https = false
 
@@ -234,7 +233,7 b' gist_alias_url ='
 #    GistView:*
 api_access_controllers_whitelist =
 
-## default encoding used to convert from and to unicode
+## Default encoding used to convert from and to unicode
 ## can be also a comma separated list of encoding in case of mixed encodings
 default_encoding = UTF-8
 
@@ -281,8 +280,8 b' allow_repo_location_change = true'
 ## allows to setup custom hooks in settings page
 allow_custom_hooks_settings = true
 
-## generated license token, goto license page in RhodeCode settings to obtain
-## new token
+## Generated license token required for EE edition license.
+## New generated token value can be found in Admin > settings > license page.
 license_token =
 
 ## supervisor connection uri, for managing supervisor and logs.

configs/production.ini

@@ -45,10 +45,9 b' debug = true'
 host = 127.0.0.1
 port = 5000
 
-##################################
-##     WAITRESS WSGI SERVER     ##
-## Recommended for Development  ##
-##################################
+###########################################################
+## WAITRESS WSGI SERVER - Recommended for Development  ####
+###########################################################
 
 #use = egg:waitress#main
 ## number of worker threads
@@ -66,15 +65,15 b' port = 5000'
 ## run with gunicorn --log-config rhodecode.ini --paste rhodecode.ini
 
 use = egg:gunicorn#main
-## Sets the number of process workers. You must set `instance_id = *`
-## when this option is set to more than one worker, recommended
-## value is (2 * NUMBER_OF_CPUS + 1), eg 2CPU = 5 workers
-## The `instance_id = *` must be set in the [app:main] section below
+## Sets the number of process workers. More workers means more concurent connections
+## RhodeCode can handle at the same time. Each additional worker also it increases
+## memory usage as each has it's own set of caches.
+## Recommended value is (2 * NUMBER_OF_CPUS + 1), eg 2CPU = 5 workers, but no more
+## than 8-10 unless for really big deployments .e.g 700-1000 users.
+## `instance_id = *` must be set in the [app:main] section below (which is the default)
+## when using more than 1 worker.
 workers = 2
-## number of threads for each of the worker, must be set to 1 for gevent
-## generally recommended to be at 1
-#threads = 1
-## process name
+## process name visible in process list
 proc_name = rhodecode
 ## type of worker class, one of sync, gevent
 ## recommended for bigger setup is using of of other than sync one
@@ -127,12 +126,12 b' gzip_responses = false'
 ## autogenerate javascript routes file on startup
 generate_js_files = false
 
-## Optional Languages
-## en(default), be, de, es, fr, it, ja, pl, pt, ru, zh
+## System global default language.
+## All available languages: en(default), be, de, es, fr, it, ja, pl, pt, ru, zh
 lang = en
 
-## perform a full repository scan on each server start, this should be
-## set to false after first startup, to allow faster server restarts.
+## Perform a full repository scan and import on each server start.
+## Settings this to true could lead to very long startup time.
 startup.import_repos = false
 
 ## Uncomment and set this path to use archive download cache.
@@ -146,23 +145,23 b' startup.import_repos = false'
 ## SSH calls. Set this for events to receive proper url for SSH calls.
 app.base_url = http://rhodecode.local
 
-## change this to unique ID for security
+## Unique application ID. Should be a random unique string for security.
 app_instance_uuid = rc-production
 
-## cut off limit for large diffs (size in bytes). If overall diff size on
+## Cut off limit for large diffs (size in bytes). If overall diff size on
 ## commit, or pull request exceeds this limit this diff will be displayed
 ## partially. E.g 512000 == 512Kb
 cut_off_limit_diff = 512000
 
-## cut off limit for large files inside diffs (size in bytes). Each individual
+## Cut off limit for large files inside diffs (size in bytes). Each individual
 ## file inside diff which exceeds this limit will be displayed partially.
 ##  E.g 128000 == 128Kb
 cut_off_limit_file = 128000
 
-## use cache version of scm repo everywhere
+## use cached version of vcs repositories everywhere. Recommended to be `true`
 vcs_full_cache = true
 
-## force https in RhodeCode, fixes https redirects, assumes it's always https
+## Force https in RhodeCode, fixes https redirects, assumes it's always https.
 ## Normally this is controlled by proper http flags sent from http server
 force_https = false
 
@@ -209,7 +208,7 b' gist_alias_url ='
 #    GistView:*
 api_access_controllers_whitelist =
 
-## default encoding used to convert from and to unicode
+## Default encoding used to convert from and to unicode
 ## can be also a comma separated list of encoding in case of mixed encodings
 default_encoding = UTF-8
 
@@ -256,8 +255,8 b' allow_repo_location_change = true'
 ## allows to setup custom hooks in settings page
 allow_custom_hooks_settings = true
 
-## generated license token, goto license page in RhodeCode settings to obtain
-## new token
+## Generated license token required for EE edition license.
+## New generated token value can be found in Admin > settings > license page.
 license_token =
 
 ## supervisor connection uri, for managing supervisor and logs.