1 files changed, 41 insertions, 0 deletions
diff --git a/app/utils.py b/app/utils.py
index 2180282..9ee0cf1 100644
--- a/app/utils.py
+++ b/app/utils.py
@@ -11,6 +11,28 @@ def _gen_tpl(endpoint):
     return endpoint.replace('.', '/') + '.jinja'
 
 def templated(template=None):
+    """Marks a view as being rendered by a template. The view then shall
+    return a dictionary holding the parameters for the template. Ig this
+    is not the case, the response is returned unchanged. This is needed
+    to support `redirect` and similar.
+
+    The correct template is deducted as:
+        - when passed nothing: the name of the view
+        - when passed a string '.bla', the endpoint 'bla' in the current
+          blueprint
+        - when passed any other string: this string (VERBATIM!)
+
+    Except for the last case, the hierarchy of blueprint and view is taken
+    as directories in the template directory. And '.jinja' is appended.
+
+    If the first argument is a function, this is taken as 'None' to allow:
+        >>> @templated
+        ... def foo():
+        ...    ...
+
+    (else it would have to be ``@templated()``).
+    """
+
     fun = None
     if template is not None and callable(template):
         # a function was passed in
@@ -41,6 +63,11 @@ def templated(template=None):
         return decorator(fun)
 
 def redirect (target, **kwargs):
+    """Convenience wrapper for `flask.redirect`. It applies `url_for`
+    on the target, which also gets passed all arguments.
+
+    Special argument '_code' to set the HTTP-Code.
+    """
     code = kwargs.pop('_code', None)
     url = url_for(target, **kwargs)
 
@@ -50,6 +77,20 @@ def redirect (target, **kwargs):
         return _redirect(url, code)
 
 def assert_authorisation(constructor, param):
+    """Asserts that the current user has the right to load some specific data.
+
+    This is done by using the argument with keyword `param` and pass it
+    to `constructor`. If the resulting object has an attribute `user_id`,
+    this is checked to be equal to `current_user.id`.
+
+    Usage example::
+
+        @route('/job/<int:id>')
+        @assert_authorisation(Job, 'id')
+        def show_job(id):
+            # this is only executed if Job(id).user_id == current_user.id
+
+    """
     def decorator(f):
         @wraps(f)
         def decorated_function(*args, **kwargs):