From 7045164de6da4dd42079e821163fa5c63b6e4946 Mon Sep 17 00:00:00 2001
From: Holger Frey <mail@holgerfrey.de>
Date: Wed, 25 Oct 2017 16:11:53 +0200
Subject: [PATCH] working on documentation

---
 ordr2/views/account.py | 48 +++++++++++++++++++++++++++++++++---------
 1 file changed, 38 insertions(+), 10 deletions(-)

diff --git a/ordr2/views/account.py b/ordr2/views/account.py
index 4695f7d..d9ef35e 100644
--- a/ordr2/views/account.py
+++ b/ordr2/views/account.py
@@ -29,6 +29,7 @@ PROPOSED_PASSWORD_LENGTH = 12
     renderer='ordr2:templates/account/login.jinja2'
     )
 def login_form(context, request):
+    ''' display a login form '''
     return {}
 
 
@@ -40,7 +41,7 @@ def login_form(context, request):
     renderer='ordr2:templates/account/login.jinja2'
     )
 def login(context, request):
-    ''' loging in a user '''
+    ''' verify user credentials and log in a user '''
     username = request.POST.get('username')
     password = request.POST.get('password')
 
@@ -68,7 +69,7 @@ def login(context, request):
     permission='logout'
     )
 def logout(context, request):
-    ''' log out an user '''
+    ''' log out of an user '''
     headers = forget(request)
     return HTTPFound(request.resource_url(request.root), headers=headers)
 
@@ -83,7 +84,7 @@ def logout(context, request):
     renderer='ordr2:templates/account/register.jinja2'
     )
 def registration_form(context, request):
-    ''' the new user registraion page '''
+    ''' display the new user registraion page '''
     form = RegistrationSchema.as_form(request)
     return {'form': form}
 
@@ -96,7 +97,11 @@ def registration_form(context, request):
     renderer='ordr2:templates/account/register.jinja2'
     )
 def registration_form_processing(context, request):
-    ''' registration form processing '''
+    ''' registration form processing
+
+    if the form validation is successfull, a user-registration-token is issued
+    and send to the provided email address for verification.
+    '''
     if 'Cancel' in request.POST:
         return HTTPFound(request.resource_url(request.root))
 
@@ -151,7 +156,10 @@ def registration_confirmation(context, request):
     renderer='ordr2:templates/account/registration_completed.jinja2'
     )
 def registration_completed(context, request):
-    ''' registration was verified by mail link '''
+    ''' registration was verified by mail link
+
+    The role of the user is changed to 'NEW' and the token is deleted
+    '''
     context.model.owner.role = Role.NEW
     request.dbsession.delete(context.model)
     return {}
@@ -167,7 +175,7 @@ def registration_completed(context, request):
     renderer='ordr2:templates/account/forgot_password_form.jinja2'
     )
 def forgot_password_form(context, request):
-    ''' forgot password form '''
+    ''' display a form to send a password recovery link '''
     return {}
 
 
@@ -179,7 +187,11 @@ def forgot_password_form(context, request):
     renderer='ordr2:templates/account/forgot_password_form.jinja2'
     )
 def forgot_password_form_processing(context, request):
-    ''' forgot password form processing '''
+    ''' process the form for password recovery links
+
+    if the validation is successful, a reset-password-token is issued and and
+    email with a link for resetting the password is send.
+    '''
     if 'cancel' in request.POST:
         return HTTPFound(request.resource_url(request.root))
 
@@ -213,7 +225,7 @@ def forgot_password_form_processing(context, request):
     renderer='ordr2:templates/account/forgot_password_email.jinja2'
     )
 def forgot_password_email_sent(context, request):
-    ''' password reset link was sent '''
+    ''' display a note that the password reset link was sent '''
     return {}
 
 
@@ -224,6 +236,7 @@ def forgot_password_email_sent(context, request):
     renderer='ordr2:templates/account/reset_password.jinja2'
     )
 def reset_password_form(context, request):
+    ''' display a reset password form '''
     form = ResetPasswordSchema.as_form(request)
     return {'form': form}
 
@@ -235,6 +248,11 @@ def reset_password_form(context, request):
     renderer='ordr2:templates/account/reset_password.jinja2'
     )
 def reset_password_form_processing(context, request):
+    ''' process the reset password form
+
+    if the form validation is successsful, the new password is set and the
+    password-reset-token deleted
+    '''
     if 'Cancel' in request.POST:
         return HTTPFound(request.resource_url(request.root))
 
@@ -273,6 +291,7 @@ def reset_password_form_processing(context, request):
     renderer='ordr2:templates/account/settings.jinja2'
     )
 def settings_form(context, request):
+    ''' display the settings form for the current user '''
     prefill = {
         'general': {
             'username': context.model.username,
@@ -295,6 +314,12 @@ def settings_form(context, request):
     renderer='ordr2:templates/account/settings.jinja2'
     )
 def settings_form_processing(context, request):
+    ''' process the settings form of the current user
+
+    if the email has changed, a verify-email-token is issued and an email sent
+    to the new address to verify it. As long as the new email is not verified,
+    it will not be set as the account email.
+    '''
     if 'Cancel' in request.POST:
         return HTTPFound(request.resource_url(request.root))
 
@@ -353,7 +378,7 @@ def settings_form_processing(context, request):
     renderer='ordr2:templates/account/email_confirmation.jinja2'
     )
 def email_confirmation(context, request):
-    ''' email sent to new address  '''
+    ''' short note, that an email was sent to new address '''
     return {}
 
 
@@ -362,7 +387,10 @@ def email_confirmation(context, request):
     permission='settings'
     )
 def email_change_confirmed(context, request):
-    ''' changed email address is confirmed '''
+    ''' the new email address is confirmed by the link in the mail
+
+    the email address is updated to the new one and the token is deleted
+    '''
     context.model.owner.email = context.model.payload['new_email']
     request.dbsession.delete(context.model)
     request.session.flash('Email change sucessful', 'success')