# HG changeset patch
# User Martin Bornhold <martin@rhodecode.com>
# Date 2016-07-26 07:44:44
# Node ID 01b438e01c5efc3dd57e78faaa41fce0f9810ece
# Parent  61adadbc135c6abf4d136ce6ce758dc4159c6e9d

svn: Update and add doc strings and comments.

diff --git a/rhodecode/svn_support/__init__.py b/rhodecode/svn_support/__init__.py
--- a/rhodecode/svn_support/__init__.py
+++ b/rhodecode/svn_support/__init__.py
@@ -35,12 +35,14 @@ def includeme(config):
     _sanitize_settings_and_apply_defaults(settings)
 
     if settings[keys.generate_config]:
-        log.error('Add subscriber')
         config.add_subscriber(
             generate_mod_dav_svn_config, events.RepoGroupEvent)
 
 
 def _sanitize_settings_and_apply_defaults(settings):
+    """
+    Set defaults, convert to python types and validate settings.
+    """
     # Convert bool settings from string to bool.
     settings[keys.generate_config] = str2bool(
         settings.get(keys.generate_config, 'false'))
@@ -53,9 +55,9 @@ def _sanitize_settings_and_apply_default
     settings.setdefault(keys.parent_path_root, None)
 
     # Append path separator to paths.
-    settings[keys.location_root] = _append_slash(
+    settings[keys.location_root] = _append_path_sep(
         settings[keys.location_root])
-    settings[keys.parent_path_root] = _append_slash(
+    settings[keys.parent_path_root] = _append_path_sep(
         settings[keys.parent_path_root])
 
     # Validate settings.
@@ -63,7 +65,10 @@ def _sanitize_settings_and_apply_default
         assert settings[keys.config_file_path] is not None
 
 
-def _append_slash(path):
+def _append_path_sep(path):
+    """
+    Append the path separator if missing.
+    """
     if isinstance(path, basestring) and not path.endswith(os.path.sep):
         path += os.path.sep
     return path
diff --git a/rhodecode/svn_support/keys.py b/rhodecode/svn_support/keys.py
--- a/rhodecode/svn_support/keys.py
+++ b/rhodecode/svn_support/keys.py
@@ -19,7 +19,8 @@
 # and proprietary license terms, please see https://rhodecode.com/licenses/
 
 
-# Settings keys used in the ini file.
+# Definition of setting keys used to configure this module. Defined here to
+# avoid repetition of keys throughout the module.
 config_file_path = 'svn.proxy.config_file_path'
 generate_config = 'svn.proxy.generate_config'
 list_parent_path = 'svn.proxy.list_parent_path'
diff --git a/rhodecode/svn_support/subscribers.py b/rhodecode/svn_support/subscribers.py
--- a/rhodecode/svn_support/subscribers.py
+++ b/rhodecode/svn_support/subscribers.py
@@ -31,11 +31,25 @@ log = logging.getLogger(__name__)
 
 
 def generate_mod_dav_svn_config(event):
-    _generate(event.request)
+    """
+    Subscriber to the `rhodcode.events.RepoGroupEvent`. This triggers the
+    automatic generation of mod_dav_svn config file on repository group
+    changes.
+    """
+    _generate(event.request.registry.settings)
 
 
-def _generate(request):
-    settings = request.registry.settings
+def _generate(settings):
+    """
+    Generate the configuration file for use with subversion's mod_dav_svn
+    module. The configuration has to contain a <Location> block for each
+    available repository group because the mod_dav_svn module does not support
+    repositories organized in sub folders.
+
+    Currently this is only used by the subscriber above. If we extend this
+    to include it as API method and in the web interface this should be moved
+    to an appropriate place.
+    """
     filepath = settings[keys.config_file_path]
     repository_root = settings[keys.parent_path_root]
     list_parent_path = settings[keys.list_parent_path]
diff --git a/rhodecode/svn_support/templates/mod-dav-svn.conf.mako b/rhodecode/svn_support/templates/mod-dav-svn.conf.mako
--- a/rhodecode/svn_support/templates/mod-dav-svn.conf.mako
+++ b/rhodecode/svn_support/templates/mod-dav-svn.conf.mako
@@ -1,5 +1,13 @@
-# This file is auto generated by RhodeCode. It contains the configuration for
-# use with mod_dav_svn.
+# Auto generated configuration for use with the Apache mod_dav_svn module.
+
+# The mod_dav_svn module does not support subversion repositories which are
+# organized in subfolders. To support the repository groups of RhodeCode it is
+# required to provide a <Location> block for each group pointing to the
+# repository group sub folder.
+
+# To ease the configuration RhodeCode auto generates this file whenever a
+# repository group is created/changed/deleted. Auto generation can be configured
+# in the ini file.
 
 <Location ${location_root}>
     DAV svn