--- a/configmix/variables.py	Thu Mar 22 16:22:22 2018 +0100
+++ b/configmix/variables.py	Thu Mar 22 16:55:12 2018 +0100
@@ -74,15 +74,32 @@
 
 
 def add_filter(name, fn):
+    """Register a variable filter with name `name` and implementation `fn`
+
+    """
     _filter_registry[_normalized(name)] = fn
 
 
 def lookup_filter(name):
+    """Lookup a variable filter with name `name` and return it's implementation
+    function
+
+    """
     return _filter_registry[_normalized(name)]
 
 
 def filter(name):
-    """Decorator for a filter function"""
+    """Decorator for a filter function.
+
+    Example usage::
+
+       @filter("myfilter")
+       def myfilter_impl(appconfig, variable_value):
+           filtered_value = ...
+           return filtered_value
+
+
+    """
 
     def _decorator(f):
 
@@ -107,7 +124,10 @@
 
     @filter("urlquote")
     def urlquote(config, v):
-        """Replace all special characters in string using the ``%xx`` escape"""
+        """Filter function to replace all special characters in string using
+        the ``%xx`` escape
+
+        """
         from urllib import quote
         return quote(v.encode("utf-8"), safe=b"").decode("utf-8")
 
@@ -115,14 +135,18 @@
 
     @filter("urlquote")
     def urlquote(config, v):
-        """Replace all special characters in string using the ``%xx`` escape"""
+        """Filter function to replace all special characters in string using
+        the ``%xx`` escape
+
+        """
         from urllib.parse import quote
         return quote(v, safe="")
 
 
 @filter("saslprep")
 def saslprep(config, v):
-    """Do a `SASLprep` according to :rfc:`4013` on `v`.
+    """Filter function to perform a `SASLprep` according to :rfc:`4013` on
+    `v`.
 
     This is a Stringprep Profile for usernames and passwords
 
@@ -133,24 +157,29 @@
 
 @filter("normpath")
 def normpath_impl(config, v):
+    """Implementation of the `normpath` filter function"""
     return os.path.normpath(v)
 
 
 @filter("abspath")
 def abspath_impl(config, v):
+    """Implementation of the `abspath` filter function"""
     return os.path.abspath(v)
 
 
 @filter("posixpath")
 def posixpath_impl(config, v):
+    """Implementation of the `posixpath` filter function"""
     return v.replace(u('\\'), u('/'))
 
 
 @filter("lower")
 def lower_impl(config, v):
+    """Implementation of the `lower` filter function"""
     return v.lower()
 
 
 @filter("upper")
 def upper_impl(config, v):
+    """Implementation of the `upper` filter function"""
     return v.upper()